Skip to content

Troubleshooting

Common issues and how to resolve them, grouped by area.

Database Issues

OperationalError: Connection refused at startup

Cause: The service started before PostgreSQL was ready.

Fix: Docker Compose uses healthchecks — this should not happen. If it does: 

docker compose restart auth-service   # retry after DB is healthy

asyncpg.exceptions.InvalidAuthorizationSpecificationError

Cause: Wrong password in the connection string.

Fix: Check DATABASE_URL in the affected service's envs/<service>.env against POSTGRES_PASSWORD in the root .env — they must match. Make sure you did not accidentally modify the password segment when copying it.

Alembic migration fails at startup

Symptom: In the service logs you see alembic.util.exc.CommandError or relation "xxx" already exists.

Fix:

  1. Check if a partial migration ran: docker exec -it jinbocho-postgres psql -U postgres -d jinbocho -c '\dt auth.*' (or catalog.*) and inspect alembic_version
  2. If the schema is in an inconsistent state, reset it: 
    # Drop and recreate the schema inside the jinbocho-postgres container, then restart
# (Alembic will rerun all migrations from scratch)
docker exec -it jinbocho-postgres psql -U postgres -d jinbocho -c 'DROP SCHEMA auth CASCADE;'
docker compose -f docker/docker-compose.all.yml --env-file .env restart auth-service

Service-to-Service Issues

Catalog service returns 401 for every request

Cause: JWT_SECRET_KEY on catalog-service does not match auth-service.

Fix: Confirm that JWT_SECRET_KEY is exactly the same string in auth, catalog, and gateway environment variables. Copy-paste errors (trailing spaces, newlines) are common.

Gateway returns 502 Bad Gateway

Cause: The gateway cannot reach an internal service.

Checks:

  1. The internal service URL in the gateway env (AUTH_SERVICE_URL/CATALOG_SERVICE_URL in envs/api-gateway.env) is wrong — it should be the Docker Compose service name, e.g. http://auth-service:8001, not localhost
  2. The service is still starting or has crashed — check its logs: docker compose -f docker/docker-compose.all.yml logs auth-service

Frontend / CORS Issues

CORS error in browser console: Access-Control-Allow-Origin missing

Cause: The gateway's CORS_ORIGINS does not include the frontend URL.

Fix:

  1. Edit envs/api-gateway.env
  2. Set CORS_ORIGINS to the exact frontend origin: ["https://library.example.com"]
  3. No trailing slash
  4. Must be a valid JSON array (double quotes, square brackets)
  5. Restart the gateway: docker compose -f docker/docker-compose.all.yml --env-file .env restart api-gateway

Frontend shows blank page after deploy

Cause: API_BASE_URL in the root .env is wrong or missing — the frontend container injects it into /env.js at startup, not at build time.

Fix: Check API_BASE_URL in .env, then restart the frontend container: docker compose -f docker/docker-compose.all.yml --env-file .env restart frontend. No rebuild needed.

Login succeeds but all subsequent API calls return 401

Cause: The access token is being sent correctly but the gateway or a backend service is rejecting it.

Checks:

  1. Open browser DevTools → Network tab → inspect a failing request's Authorization header
  2. Confirm JWT_SECRET_KEY is identical on auth, catalog, and gateway

ISBN Lookup Issues

ISBN lookup returns 404 for a valid ISBN

Cause: The book is not in Open Library or Google Books, or the Google Books API key is missing/invalid.

Checks:

  1. Test Open Library directly: 
    curl "https://openlibrary.org/api/books?bibkeys=ISBN:9788845292613&format=json&jscmd=data"
  2. If GOOGLE_BOOKS_API_KEY is missing, the fallback lookup is skipped — add the key to envs/catalog-service.env

ISBN lookup is slow (> 2 seconds)

Cause: The ISBN is not in the local cache, and the external lookup is slow.

Fix: Expected for the first lookup of any ISBN. Subsequent lookups for the same ISBN are cached and fast.

General

Port already in use

# Find the process using port 8000
lsof -i :8000

# Kill it
kill -9 <PID>

# Or change the host-side port in the compose file (e.g. "8010:8000")