Skip to content

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

ObservationNext check
No startup logProduction entrypoint and dependencies
Import failureModule path and service working directory
Local listener onlyBind interface and assigned port
Health route failsActual path, prefix and readiness dependencies
Failure appears under loadMemory, 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.

References