Fix: 502 Bad Gateway (Azure App Service)

A 502 Bad Gateway on Azure App Service means the platform’s front end accepted the request, handed it toward your worker process, and did not get a valid response back. Your code, not the Azure edge, is the usual suspect: the worker crashed, hung beyond the platform’s request timeout, or was mid restart when the request arrived. App Service records enough diagnostics to name the failing layer, and pulling those beats redeploying on a hunch every time.

502 Bad Gateway (Azure App Service)

What this error means

App Service fronts every app with a shared front end layer that proxies requests to the worker instances running your code. A 502 is that proxy reporting a failed exchange: the worker connection was refused or reset, the response was malformed, or no response arrived before the platform’s hard request limit (about 230 seconds for HTTP traffic, 240 on some stacks; it is not configurable upward). The same symptom therefore covers several distinct diseases: a crashed process, a deadlocked one, an app stuck in startup after a recycle, or an upstream of your own that your code waits on forever.

Common causes

• The worker process crashes on certain requests: unhandled exceptions, native module faults, or out of memory recycles.
• A request legitimately runs past the 230 second platform limit, common with report generation and big file processing.
• Thread pool starvation: synchronous blocking inside async request paths, so requests queue until the front end gives up.
• A deployment or slot swap switched traffic before the new worker was warm, or the app fails to start under new settings.
• SNAT port exhaustion or a dead outbound dependency, making handlers hang on external calls until the platform cuts them off.
• Memory or CPU exhaustion on an undersized plan, triggering recycles under peak load.

How to fix it

STABILIZE first. If the onset matches a deploy or swap, swap back or redeploy the last good build. If the app is wedged with no recent change, restart it to restore service while you pull diagnostics:

az webapp restart --name my-app --resource-group rg

1. DIAGNOSE with the platform’s own detectors before anything else. In the portal, open Diagnose and solve problems and run Web App Down and HTTP Server Errors; they correlate 502s with worker crashes, recycles, SNAT, and memory automatically.

2. Pull the recent HTTP and application logs and look at what the worker was doing when responses stopped:

az webapp log config --name my-app --resource-group rg \
  --application-logging filesystem \
  --detailed-error-messages true \
  --web-server-logging filesystem

az webapp log tail --name my-app --resource-group rg

Crashes show as process exits and startup banners repeating. Hangs show as requests entering and never completing.

3. Check whether requests are hitting the platform time limit. Anything that genuinely needs minutes must move off the request path: queue the work (Storage queues, Service Bus) and let a WebJob or Functions worker process it, returning the result asynchronously. No App Service setting extends the front end timeout past its limit.

4. FIX crashes at the source: read the stack trace from application logs or the event log (Windows plans expose it via the Kudu console at https://my-app.scm.azurewebsites.net), fix the exception, and watch memory working set to see if the OOM killer or platform recycler is ending the process:

az monitor metrics list \
  --resource /subscriptions/<sub-id>/resourceGroups/rg/providers/Microsoft.Web/sites/my-app \
  --metric MemoryWorkingSet,Http5xx \
  --interval PT5M

5. FIX deploy time 502s with warmup: enable the health check feature on the app, point it at a cheap readiness path, and for slot swaps set WEBSITE_SWAP_WARMUP_PING_PATH and WEBSITE_SWAP_WARMUP_PING_STATUSES so the platform only swaps once the new worker answers correctly. Scale out to at least two instances so one recycling worker cannot take the whole app down.

How to prevent it

• Enable App Service health check on every production app so bad instances are pulled and replaced automatically.
• Run at least two instances; single instance production apps convert every recycle into an outage.
• Keep long work off the request thread: queue it and process in the background, always under the 230 second ceiling.
• Alarm on Http5xx, MemoryWorkingSet, and response time trends rather than waiting for users.
• Use deployment slots with warmup for every release so traffic never reaches a cold worker.

When to call a senior engineer

Call for help when 502s stay intermittent across restarts and detectors disagree, when a crash only reproduces under production traffic, or when the fix requires re architecting long running requests without breaking clients. Erzon engineers can read the worker process history, memory dumps, and request traces to name the exact failure, get the app stable on the current plan, and restructure the hot paths so the platform limits stop being your outage trigger.