Skip to content

Troubleshooting

Check service health

Run the built-in health check script:

npm run health-check

Or check each service manually:

curl http://localhost:3001/health   # Backend
curl http://localhost:3000/         # Frontend
curl http://localhost:3002/health   # Azure module (if enabled)

View logs

# All services
docker compose -f docker-compose.generated.yml logs -f

# Specific service
docker compose -f docker-compose.generated.yml logs -f backend

# Last 100 lines
docker compose -f docker-compose.generated.yml logs --tail=100 backend

Common issues

Database connection failed

Symptom: Backend health check fails with a database error. Logs show connection refused or password authentication failed.

Steps:

  1. Confirm the database container is running:

    bash docker compose -f docker-compose.generated.yml ps postgres

  2. Verify DATABASE_URL or POSTGRES_* variables in .env are correct.

  3. Check database logs:

    bash docker compose -f docker-compose.generated.yml logs postgres

Module not starting

Symptom: A module container exits immediately after starting.

Steps:

  1. Check the module is set to enabled: true in strawly-deployment.yml.

  2. Check that all required credentials are in .env (e.g. AZURE_TENANT_ID for the Azure module).

  3. View the module logs:

    bash docker compose -f docker-compose.generated.yml logs optimizations-azure

Port already in use

Symptom: Error: bind: address already in use when starting services.

Steps:

  1. Find what is using the port:

    bash ss -tlnp | grep 3001

  2. Either stop the conflicting process, or change the port in strawly-deployment.yml:

    yaml core: backend: port: 3011 # changed from 3001

  3. Regenerate and redeploy:

    bash npm run generate-compose docker compose -f docker-compose.generated.yml up -d

  4. If you changed the backend port, also update CORS_ORIGIN and any frontend environment variables that reference the backend URL.

Migrations failing

Symptom: The migrations container exits with an error and the backend does not start.

Steps:

  1. Check migration logs:

    bash docker compose -f docker-compose.generated.yml logs migrations

  2. Common causes: database is not yet reachable (timing issue — re-running usually resolves it), or DATABASE_URL is incorrect.

  3. Re-run the stack:

    bash docker compose -f docker-compose.generated.yml up -d

Frontend cannot reach the backend

Symptom: The UI loads but shows errors or empty data. Browser console shows CORS errors or network failures.

Steps:

  1. Confirm the backend is healthy: curl http://localhost:3001/health

  2. Check CORS_ORIGIN in .env matches the URL you are using to access the frontend.

  3. Regenerate and redeploy after any .env change:

    bash npm run generate-compose docker compose -f docker-compose.generated.yml up -d

Reset the database

This deletes all data permanently

Only do this if you need a clean slate. There is no undo.

docker compose -f docker-compose.generated.yml down -v
docker compose -f docker-compose.generated.yml up -d

The -v flag removes Docker volumes, including the PostgreSQL data volume. Migrations and seeding run automatically on the next startup.