Common Issues

Auth errors, env mismatches, and local vs production discrepancies.

Quick reference for the most frequently encountered development issues and their fixes.

Authentication errors

"Invalid or expired token"

Check that Cognito app client IDs match your .env.local
Verify redirect URIs include your local URL
Clear browser storage and re-login
Confirm token hasn't expired (access tokens last 1 hour)

"Redirect URI mismatch"

Add your local URL to Cognito app client settings:

plaintext

http://localhost:3000/callback
http://localhost:3000

Environment mismatches

API calls fail locally but work in staging

Compare .env.local values with staging environment
Check NEXT_PUBLIC_ values were set before build (they're baked in)
Verify the API server is running on the expected port

Database connection refused

bash

docker compose ps          # Check if postgres is running
docker compose up -d postgres redis
pnpm db:migrate            # Apply pending migrations

Port conflicts

bash

lsof -i :3000              # Find process using port 3000
kill -9 <PID>              # Stop the conflicting process
pnpm dev                   # Restart dev server

Production rollback

If a deployment causes production issues:

bash

kubectl -n production rollout history deployment/backend-api
kubectl -n production rollout undo deployment/backend-api
kubectl -n production rollout status deployment/backend-api

Always communicate in the engineering channel before rolling back.