Section 7
Common deployment errors
If your deploy isn't behaving as expected, check this table first. Most issues fall into one of these nine categories.
| Error / symptom | Likely cause | Fix |
|---|---|---|
| 502 Bad Gateway | App not listening on APP_PORT | Bind to 0.0.0.0:$APP_PORT |
| CSRF verification failed | CSRF_TRUSTED_ORIGINS not set | Add APP_DOMAIN to CSRF config (see Framework recipes → Django) |
| 413 Request Entity Too Large | File > 50 MB | Compress or use external storage |
| App crashed on start | Missing SECRET_KEY / APP_KEY | Set it in user env vars before deploy |
| Files missing after redeploy | Writing outside /app/storage | Use the APP_STORAGE path (see Persistent storage) |
| Static files 404 | collectstatic not in build command | Add collectstatic to BUILD_COMMANDS |
| DB migration failed | migrate not in run command | Run migrate before gunicorn starts |
| WebSocket disconnects | Idle connection timeout | Handled by platform — contact support |
| Port already in use | Previous deploy still shutting down | Platform handles this — redeploy |
Still stuck?Open your project in the dashboard and check the real-time logs tab — your app's stdout/stderr output is streamed live and usually shows the exact error within the first few lines of startup.
Need more help?
If you've checked the logs and the error isn't listed here, reach out to support. Include your project ID (APP_ID) and the first 20 lines of your startup log.