Skip to content
TheTerms Docs

Troubleshooting

Container Won’t Start

Section titled “Container Won’t Start”

Symptom: docker compose ps shows the app container as Exit 1 or restarting.

Diagnose:

Terminal window
docker compose logs app

Common causes:

  • Missing or invalid NEXTAUTH_SECRET — generate with openssl rand -base64 32
  • NEXTAUTH_URL not set or doesn’t match your domain
  • Postgres or Redis not yet healthy (wait a few seconds and retry)

Migration Errors on Startup

Section titled “Migration Errors on Startup”

Symptom: Logs show Migration failed or Prisma errors.

Diagnose:

Terminal window
docker compose logs app | grep -i migration

Common causes:

  • DATABASE_URL incorrect — Docker Compose sets this automatically, but if you’ve overridden it, check the connection string
  • Postgres container not healthy — check docker compose ps postgres
  • Insufficient database permissions

Fix: Ensure Postgres is running and healthy before the app starts:

Terminal window
docker compose up -d postgres redis
docker compose ps  # wait until postgres shows "healthy"
docker compose up -d app

Emails Not Sending

Section titled “Emails Not Sending”

Symptom: Signing invitations or team invitations are not delivered.

Causes and fixes:

  • RESEND_API_KEY is missing or invalid — verify in your .env and restart
  • EMAIL_FROM domain not verified in Resend — add and verify your domain at resend.com
  • Check Resend dashboard logs for delivery errors

OAuth Callback Error

Section titled “OAuth Callback Error”

Symptom: “OAuthCallbackError” or redirect loop after Google/Microsoft sign-in.

Cause: The OAuth redirect URI doesn’t match NEXTAUTH_URL.

Fix:

  1. Ensure NEXTAUTH_URL is set to your exact public URL, including https:// and without a trailing slash
  2. In your OAuth provider’s settings, set the authorized redirect URI to:
    • Google: https://your-domain.com/api/auth/callback/google
    • Microsoft: https://your-domain.com/api/auth/callback/azure-ad
  3. Restart after changing .env: docker compose up -d

Port Conflict

Section titled “Port Conflict”

Symptom: bind: address already in use when starting containers.

Fix: Change the exposed port in .env:

Terminal window
PORT=3001

Then restart: docker compose up -d

Database Connection Refused

Section titled “Database Connection Refused”

Symptom: App logs show connect ECONNREFUSED to the database.

Fix:

Terminal window
# Check postgres is running
docker compose ps postgres


# Check postgres is healthy
docker compose exec postgres pg_isready -U postgres

If the database is not healthy, check its logs:

Terminal window
docker compose logs postgres

Slow Performance

Section titled “Slow Performance”

PostgreSQL tuning: For servers with 4+ GB RAM, add these to the Postgres service in docker-compose.yml:

environment:
  POSTGRES_SHARED_BUFFERS: "256MB"
  POSTGRES_EFFECTIVE_CACHE_SIZE: "1GB"
  POSTGRES_MAX_CONNECTIONS: "100"

Connection pooling: For high-traffic deployments, consider adding PgBouncer between the app and PostgreSQL.