Docs

Troubleshooting 502 and 504 Errors

Overview

A 502 (Bad Gateway) or 504 (Gateway Timeout) error means the request successfully reached the WAF edge network, passed all security checks, but the WAF could not get a valid response from your Heroku application.

Client → WAF Edge ✓ → Your Heroku App ✕ (not responding)

This is different from a 403 WAF block (where the WAF rejected the request) and from a connection timeout (where the request never reached the WAF at all). See Understanding HTTP Responses and Network Timeouts for how to tell these apart.

502 — Bad Gateway

Your Heroku application is not responding at all. The WAF forwarded the request but got no valid response back.

Common Causes

Dynos are down or crashed — Your Heroku dynos are not running. - Check dyno status: heroku ps - Check logs for crash errors: heroku logs --tail - Look for H10 (App Crashed) errors

Out of memory — Your app is exceeding its memory quota. - Look for R14 (Memory Quota Exceeded) or R15 (Memory Quota Vastly Exceeded) in logs

Boot timeout — Your app takes too long to start up. - Look for H20 (App Boot Timeout) errors

DNS misconfiguration — The WAF cannot route requests to your origin. - Verify your DNS records match what is shown on your WAF setup page

Quick Test

Visit your app directly at its .herokuapp.com URL. If you see errors there too, the problem is your Heroku application — not the WAF.

504 — Gateway Timeout

Your Heroku application is responding, but too slowly. The WAF has a timeout window, and your app did not respond within it.

Common Causes

Slow database queries — A query is taking too long to return results.

External API calls — Your app is waiting on a third-party API that is slow or unresponsive.

Large file uploads or processing — The request involves heavy processing that exceeds the timeout window.

Heroku H12 timeout — Heroku itself has a 30-second request timeout. If your app exceeds this, Heroku terminates the request before the WAF timeout even comes into play.

Fix

Identify the slow endpoint in your Heroku logs and optimize it. Move long-running operations to background jobs (Sidekiq, etc.) instead of handling them in the request cycle.

Diagnostic Steps

  1. Check your origin directly — Visit https://your-app.herokuapp.com to confirm your Heroku app is responding. If it also fails, the problem is your application.

  2. Check Heroku logs — Run heroku logs --tail and look for error codes (H10, H12, H13, H14, R14, etc.).

  3. Check dyno status — Run heroku ps to confirm dynos are up and running.

  4. Test a simple endpoint — Try a health check or lightweight page to isolate whether it is a global issue or specific to certain routes.

  5. Check for recent deploys — Did you recently deploy code that could have introduced a bug or performance regression? Check heroku releases.

Quick Reference

Symptom Likely Cause
502 on WAF domain AND .herokuapp.com Heroku app is down — fix the app
502 on WAF domain but .herokuapp.com works WAF cannot reach origin — contact us
504 on WAF domain Origin is too slow — optimize your app response time
Intermittent 502s Dyno cycling, memory issues, or brief outages
No HTTP response at all (browser timeout) Not a 502 — see Connection Timeouts

Need Help?

If you are seeing persistent 502 or 504 errors and cannot identify the cause: