Troubleshooting · By Rivtor · Updated
Diagnose FastAPI 502 Bad Gateway after deployment
A 502 response usually indicates that a proxy could not obtain a usable response from the upstream application. Check startup, listener, health path, resource exhaustion and request timing before changing FastAPI code or database credentials.
See the Rivtor deployment workflow →
Locate the response and the failed request
Record the public URL, timestamp, HTTP method and a request identifier if available. Determine whether the 502 comes from the front proxy or the application. Compare health with the actual failing route; a healthy root path does not prove a database-backed endpoint works.
Do not assume every 502 has the same cause. A process that never starts, a crash under load and a long request interrupted by a proxy can look similar in the browser but require different fixes.
Work through the listener boundary
| Observation | Next check |
|---|---|
| No startup log | Production entrypoint and dependencies |
| Import failure | Module path and service working directory |
| Local listener only | Bind interface and assigned port |
| Health route fails | Actual path, prefix and readiness dependencies |
| Failure appears under load | Memory, database wait and blocked event loop |
An illustrative Uvicorn command for a main.py exporting app is:
uvicorn main:app --host 0.0.0.0 --port 8000
Use the port and import path configured for the selected service. This is a command-shape example, not a production deployment measurement.
Separate crashes from slow requests
Check process exits and memory-related termination near the failing timestamp. If only long operations fail, measure application and upstream API duration separately. Increasing a timeout can mask a blocked worker or exhausted connection pool; first identify the resource the request is waiting for.
In an async endpoint, blocking network or CPU work can prevent other requests from progressing. Move durable long work to an appropriate worker rather than assuming a longer HTTP request is the right design.
Verify the repair with a representative route
On Rivtor, read the structured stage and error in the error reference, then inspect the configured health path and service root. Test a lightweight route and a synthetic database-backed operation separately. Repeat at representative concurrency, restart the service and confirm the corrected configuration remains. Record the failure class and change made so a transient successful retry is not mistaken for a repaired cause.