Troubleshooting

Common issues and their solutions when developing BISO Sites.

Installation & Setup

Bun Installation Fails

Problem: Can't install Bun or getting errors

Solution:

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Restart terminal
source ~/.bashrc  # or ~/.zshrc

# Verify installation
bun --version

Dependencies Won't Install

Problem: bun install fails or hangs

Solutions:

Clear cache and retry:

rm -rf node_modules apps/*/node_modules packages/*/node_modules
rm bun.lock
bun install

Check Node.js version (requires >= 18):

node --version

Try with clean environment:

rm -rf ~/.bun
curl -fsSL https://bun.sh/install | bash

Development Server

Port Already in Use

Problem: Error: Port 3000 is already in use

Solutions:

Kill the process:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Change the port in package.json:

{
  "scripts": {
    "dev": "next dev -p 3050"
  }
}

Hot Reload Not Working

Problem: Changes not reflecting in browser

Solutions:

Hard refresh browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Restart dev server
Clear Next.js cache:

cd apps/web
rm -rf .next
bun run dev

Check file is saved
Ensure using correct port

Dev Server Crashes

Problem: Server crashes with memory errors

Solution:

# Increase Node memory
NODE_OPTIONS=--max-old-space-size=4096 bun run dev

Build Errors

Type Errors

Problem: TypeScript errors during build

Solutions:

Generate Next.js types:

cd apps/web
bunx next build --typegen-only

Check for import errors:

// ❌ Wrong
import { Button } from '@repo/ui/button'

// ✅ Correct
import { Button } from '@repo/ui/components/ui/button'

Restart TypeScript server in VS Code:

Cmd+Shift+P → "TypeScript: Restart TS Server"

Module Not Found

Problem: Module not found: Can't resolve '@repo/...'

Solutions:

Reinstall dependencies:

bun install

Check tsconfig.json paths:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@repo/ui": ["../../packages/ui"],
      "@repo/api": ["../../packages/api"]
    }
  }
}

Ensure package exists in workspace

Build Fails with "Out of Memory"

Solution:

NODE_OPTIONS=--max-old-space-size=8192 bun run build

Or in package.json:

{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=8192 next build"
  }
}

Database & API

Appwrite Connection Failed

Problem: Can't connect to Appwrite

Solutions:

Check environment variables:

# Verify .env.local exists
ls -la apps/web/.env.local

# Check contents
cat apps/web/.env.local

Verify endpoint is accessible:

curl https://your-appwrite.com/v1/health/version

Check browser console for CORS errors
Verify project ID matches Appwrite dashboard

Session Not Found (401 Error)

Problem: Getting unauthorized errors

Solutions:

Check cookie is set:

Open browser DevTools → Application → Cookies
Look for a_session_biso cookie

Verify session client usage:

// ✅ Correct
const { account } = await createSessionClient();
const user = await account.get();

// ❌ Wrong (no session)
const { account } = await createAdminClient();
const user = await account.get();

Re-login to get new session

Database Permission Denied

Problem: Can't read/write documents

Solutions:

Check Appwrite collection permissions
Verify user has required role
Use admin client for system operations:

// In webhook/system operation
const { db } = await createAdminClient();

Payment Issues

Vipps Test Mode Not Working

Problem: Payment fails in test mode

Solutions:

Verify test mode enabled:

VIPPS_TEST_MODE=true

Use test card numbers:

Card: 4925 0000 0000 0004
Expiry: Any future date
CVC: Any 3 digits

Check Vipps credentials are for test environment

Webhook Not Received

Problem: Order stuck in PENDING

Solutions:

Check webhook URL is accessible from internet
Verify webhook URL in Vipps dashboard
Check server logs for incoming requests
Test webhook manually:

curl -X POST http://your-domain.com/api/payment/vipps/callback?sessionId=test_123

Use ngrok for local testing:

ngrok http 3000
# Use ngrok URL in Vipps dashboard

Styling Issues

Tailwind Classes Not Working

Problem: Styles not applying

Solutions:

Check tailwind.config.cjs includes file:

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    '../../packages/ui/components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

Restart dev server after config changes
Ensure classes are in content files (not dynamically generated):

// ❌ Wrong (dynamic classes)
className={`text-${color}-500`}

// ✅ Correct
className={color === 'blue' ? 'text-blue-500' : 'text-red-500'}

Dark Mode Not Working

Problem: Theme toggle doesn't work

Solutions:

Ensure ThemeProvider is in layout:

import { ThemeProvider } from '@repo/ui/components/theme-provider';

<html suppressHydrationWarning>
  <body>
    <ThemeProvider>
      {children}
    </ThemeProvider>
  </body>
</html>

Add suppressHydrationWarning to <html> tag
Use theme-aware classes:

className="bg-white dark:bg-gray-900"

Git & Version Control

Merge Conflicts

Problem: Git merge conflicts

Solutions:

View conflicts:

git status

Resolve manually in editor, looking for:

<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> branch-name

After resolving:

git add .
git commit -m "fix: resolve merge conflicts"

Accidentally Committed Secrets

Problem: Committed API keys to repo

Solutions:

Remove from history:

# Install BFG Repo Cleaner
brew install bfg

# Remove secrets
bfg --replace-text passwords.txt

# Force push (⚠️ dangerous)
git push --force

Rotate all exposed secrets immediately
Add to .gitignore:

.env.local
.env*.local

Performance Issues

Slow Page Load

Solutions:

Use Server Components by default
Minimize client-side JavaScript
Optimize images:

import Image from 'next/image';

<Image
  src="/image.jpg"
  width={800}
  height={600}
  alt="Description"
/>

Use loading="lazy" for images below fold

Large Bundle Size

Solutions:

Analyze bundle:

cd apps/web
ANALYZE=true bun run build

Use dynamic imports:

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Loading...</p>
});

Check for duplicate dependencies

VS Code Issues

IntelliSense Not Working

Solutions:

Restart TypeScript server:

Cmd+Shift+P → "TypeScript: Restart TS Server"

Reload window:

Cmd+Shift+P → "Developer: Reload Window"

Check .vscode/settings.json:

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Format on Save Not Working

Solution:

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Deployment Issues

Build Fails in Production

Solutions:

Check environment variables are set
Increase build timeout
Use build:appwrite script for Appwrite:

bun run build:appwrite

Environment Variables Not Found

Problem: process.env.SOMETHING is undefined

Solutions:

Check variable is in .env.local
Restart dev server after adding variables
For client-side, prefix with NEXT_PUBLIC_:

NEXT_PUBLIC_APPWRITE_ENDPOINT=...

Getting Help

If you're still stuck:

Check logs - Terminal and browser console
Search issues - GitHub issues or documentation
Simplify - Create minimal reproduction
Ask for help - Team chat or create issue

💡

Debug Mode

Set DEBUG=true in .env.local for verbose logging.

Prevention

Best Practices to Avoid Issues

Keep dependencies updated - Run bun update regularly
Clear cache periodically - rm -rf .next .turbo
Use TypeScript strict mode - Catch errors early
Test before committing - Run bun run check-types && bun run lint
Read error messages - They usually tell you what's wrong
Keep .env.example updated - Document required variables

Quick Fixes Checklist

When something breaks:

Restart dev server
Hard refresh browser
Clear Next.js cache (rm -rf .next)
Reinstall dependencies (rm -rf node_modules && bun install)
Check for type errors (bun run check-types)
Check browser console for errors
Check terminal for errors
Verify environment variables
Try in incognito/private window

Next Steps

Commands Reference - All available commands
Development Workflow - Daily development guide
Contributing - How to contribute

ℹ️

Found a solution not listed here? Consider contributing it to the docs!

Troubleshooting

On this page