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:

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

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

3. Check database logs:

   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 CREDENTIALS_ENCRYPTION_KEY is set and matches the backend's value, so the module can decrypt the credentials stored in the database. (Cloud provider credentials themselves are entered in the UI, not in .env.)

3. View the module logs:

   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:

   ss -tlnp | grep 3001
   

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

   core:
     backend:
       port: 3011   # changed from 3001
   

3. Regenerate and redeploy:

   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:

   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:

   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:

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

Reset the database¶

Take a backup first:

docker exec strawly-postgres pg_dump -U strawly strawly \
  | openssl enc -aes-256-cbc -pbkdf2 -salt \
  -out backup-before-reset-$(date +%Y%m%d-%H%M%S).sql.enc

Then reset:

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 the seeder run automatically on the next startup, restoring system roles and the admin account from ADMIN_EMAIL/ADMIN_PASSWORD in .env. Re-seed the module registry so the UI shows your enabled modules:

npm run seed-modules

Demo data is not restored automatically. Run the demo seed again if needed:

docker compose -f docker-compose.generated.yml run --rm seeder npx tsx prisma/seed.demo.ts