Troubleshooting

Common issues

1) Missing environment variable ...

Fix:

• Copy .env.example → .env.local
• Fill required values
• Restart pnpm dev

cp .env.example .env.local
pnpm dev

2) Database connection refused / timeout

Fix:

• Start Docker services
• Verify the DB port is correct
• Check DATABASE_URL

docker compose up -d
docker ps

If you changed DB credentials, recreate containers (⚠️ deletes local DB):

docker compose down -v
docker compose up -d

3) Migrations fail / schema mismatch

Fix:

• Ensure DB is up
• Re-run migrations
• If your tool supports it, reset dev DB (⚠️ deletes data)

Examples:

pnpm db:migrate
pnpm db:seed

Prisma reset (⚠️ deletes data):

pnpm prisma migrate reset

4) Auth callback / redirect URI mismatch

Symptoms:

• Login loops
• “callback URL mismatch” from provider

Fix:

• Ensure NEXT_PUBLIC_APP_URL (and AUTH_URL/NEXTAUTH_URL) matches http://localhost:3000
• Update OAuth provider redirect URIs to include your local callback URL
• Restart dev server after changes

5) Port already in use

Fix:

• Stop the process using the port or change the port

Mac/Linux quick check:

lsof -i :3000

6) Weird build / caching behavior

Fix:

• Clear Next.js cache and reinstall deps if necessary

rm -rf .next node_modules
pnpm install
pnpm dev

7) Docker issues (permissions / won’t start)

Fix:

• Ensure Docker Desktop is running
• Try restarting Docker
• On Linux, ensure your user can run Docker without sudo (team policy dependent)

What to include when escalating

When asking for help, include:

• exact command you ran
• full error output (first ~30–50 lines)
• your OS + Node version (node -v)
• whether Docker is running (docker ps)
• whether the issue is new or reproducible