Skip to content
Nodebyte

FAQ & Troubleshooting

Common Issues

Section titled “Common Issues”

Containers won’t start

Section titled “Containers won’t start”

Symptom: docker compose up fails or containers restart in a loop.

Check:

  1. Ensure Docker Engine and the Compose plugin are installed: docker compose version
  2. Check for port conflicts: lsof -i :3000 and lsof -i :8000
  3. Review container logs: docker compose logs backend or docker compose logs frontend

Database connection errors

Section titled “Database connection errors”

Symptom: Backend logs show connection refused or could not connect to server.

Fix: The database container may still be starting. Wait 10-15 seconds and check again. If persistent, verify your DATABASE_URL in .env matches the Postgres container settings.

”Invalid token” or 401 errors

Section titled “”Invalid token” or 401 errors”

Symptom: API requests return 401 Unauthorized.

Check:

  • Access tokens expire after 15 minutes by default (ACCESS_TOKEN_EXPIRES_MINUTES). The frontend auto-refreshes, but API scripts need to handle refresh or re-login.
  • Ensure JWT_SECRET hasn’t changed between requests — changing it invalidates all existing tokens.
  • For registration tokens, verify the token hasn’t been revoked and hasn’t exceeded max_uses.

CORS errors in the browser

Section titled “CORS errors in the browser”

Symptom: Browser console shows CORS policy errors.

Fix: Set FRONTEND_ORIGIN to the exact URL your frontend is served from (e.g. https://nodebyte.example.com). Include the scheme and port if non-standard.

Cookies not working in production

Section titled “Cookies not working in production”

Symptom: Login works but the session doesn’t persist (redirected to login on every page load).

Fix:

  1. Set COOKIE_SECURE=true (required for HTTPS)
  2. Set COOKIE_SAMESITE=lax (or strict if frontend and API share a domain)
  3. Ensure your reverse proxy passes the correct headers (X-Forwarded-Proto: https)

Turnstile widget not appearing

Section titled “Turnstile widget not appearing”

Symptom: The registration page doesn’t show the CAPTCHA widget.

Check:

  • In development, the test keys render an invisible widget — this is expected
  • In production, ensure NEXT_PUBLIC_TURNSTILE_SITE_KEY is set correctly
  • To disable entirely: TURNSTILE_ENABLED=false

Browser extension can’t connect

Section titled “Browser extension can’t connect”

Symptom: The extension shows a connection error.

Fix:

  1. Open extension settings and verify the API URL (e.g. http://localhost:8000)
  2. The extension talks directly to the backend — it doesn’t use the frontend proxy
  3. Ensure the backend is running and accessible from your browser’s network

Migration errors on startup

Section titled “Migration errors on startup”

Symptom: Backend fails with Alembic migration errors.

Fix:

Terminal window
docker compose exec backend alembic upgrade head

If migrations are stuck, check the alembic_version table in PostgreSQL.

Getting Help

Section titled “Getting Help”