Troubleshooting

Common issues encountered when running SLOzy and their solutions.

Database Connection Refused

Error: connection refused or could not connect to server

Causes:

• PostgreSQL service is not running
• Connection string contains incorrect host, port, or credentials
• Network firewall blocking port 5432
• Connection pool exhausted (default max: 25)

Solutions:

1. Verify PostgreSQL is running:

   systemctl status postgresql

2. Check the connection string in your .env file:

   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   POSTGRES_USER=slozy_user
   POSTGRES_DB=slozy_db

3. Test connectivity directly:

   psql -h localhost -U slozy_user -d slozy_db -c "SELECT 1"

4. Check connection pool usage:

   SELECT count(*) FROM pg_stat_activity WHERE datname = 'slozy_db';

Migration Fails

Error: dirty database version X or migration SQL error

Causes:

• Migration was interrupted mid-apply
• Schema already exists from a previous partial migration
• Incompatible SQL syntax for your PostgreSQL version

Solutions:

1. Check the schema_migrations table state:

   SELECT version, dirty FROM schema_migrations;

2. If dirty = true, review the failed migration SQL and fix any issues
3. Force-clean the dirty flag (after manual fix):

   UPDATE schema_migrations SET dirty = false WHERE version = <version>;

4. Re-run migrations:

   ./slozy-web
   # or manually:
   migrate -path migrations/ -database "postgres://..." up

5. As a last resort, rollback and retry:

   migrate -path migrations/ -database "postgres://..." down 1
   migrate -path migrations/ -database "postgres://..." up

Prometheus Query Timeout

Error: context deadline exceeded or query timeout

Causes:

• Range query covers too large a time window
• Too many time series selected simultaneously
• Prometheus data source is overloaded

Solutions:

1. Increase the query timeout in the Prometheus data source configuration
2. Reduce the query range — use shorter time windows (e.g., 7 days instead of 30)
3. Optimize PromQL queries to reduce cardinality
4. Verify Prometheus performance:

   curl http://prometheus:9090/api/v1/query?query=up

5. Check Prometheus resource usage and consider scaling

Frontend CORS Errors

Error: Cross-Origin Request Blocked in browser console

Causes:

• VITE_API_BASE_URL does not match the actual API server URL
• API server's CORS_ORIGINS does not include the frontend origin
• Using HTTP when API expects HTTPS (or vice versa)

Solutions:

1. Verify VITE_API_BASE_URL in frontend/.env.production:

   VITE_API_URL=/api/v1
   VITE_API_BASE_URL=http://localhost:8080

2. Check CORS_ORIGINS environment variable on the API server
3. For development, the Vite proxy (vite.config.ts) handles CORS:

   server: {
     proxy: {
       '/api': {
         target: 'http://localhost:8080',
         changeOrigin: true,
       }
     }
   }

4. For production, ensure the reverse proxy handles CORS headers correctly

WebSocket Not Connecting

Error: WebSocket connection fails (console shows WebSocket is closed before the connection is established)

Causes:

• WebSocket endpoint path is incorrect
• Reverse proxy not configured for WebSocket upgrade
• Network/firewall blocking WebSocket (WS/WSS) connections

Solutions:

1. Verify the WebSocket endpoint URL:
   • Uses ws:// or wss:// scheme
   • Path matches the server's WebSocket hub (e.g., ws://host/ws)
2. Ensure reverse proxy (Nginx, Traefik) supports WebSocket upgrade:

   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";

3. Check WebSocket hub configuration in internal/websocket/handler.go:

   func NewHub(ctx context.Context, allowedOrigins ...string) *Hub

4. For production, pass explicit allowed origins (not empty). Empty origins allow all connections (development mode).
5. Verify no firewall rules block port 80/443 WebSocket traffic

General Debugging

Enable debug logging by setting:

LOG_LEVEL=debug
LOG_FORMAT=text  # Use text format for easier reading

Check application logs for request-level details including middleware decisions (auth failures, rate limiting, permission denials).