Home / Azure

AzureRunbookAdvanced

Sev1: Azure Front Door returns 502 or 503 for every request — origin health, host header and Private Link fixes

Front Door suddenly serves 502/503 to all users. Check origin health probes, host header, origin TLS certificate names and Private Link approvals, then fix in the right order.

Deepak Bhardwaj4 min read

Applies toAzure Front Door Standard/Premium, Azure CLI 2.50+ (az afd)

Symptoms

  • Users get 502 Bad Gateway or 503 with an Azure Front Door error page; the origin works when you hit it directly.
  • The x-azure-ref header is present on the error response, so the request reached Front Door.
  • It started after a certificate renewal, an origin change, a WAF change or a Private Link redeploy.

1. Confirm where the request dies

# Through Front Door
curl -sv https://www.contoso.com/health -o /dev/null 2>&1 | grep -E "HTTP/|x-azure-ref"

# Straight to the origin, with the host header Front Door sends
curl -sv https://app-prod.azurewebsites.net/health -H "Host: app-prod.azurewebsites.net" -o /dev/null

If the origin answers directly but not through Front Door, the problem is in the Front Door to origin hop: probes, host header, TLS or Private Link.

2. Check origin health and the access log

AzureDiagnostics
| where Category == "FrontDoorAccessLog"
| where TimeGenerated > ago(30m)
| summarize count() by httpStatusCode_s, errorInfo_s, originName_s
| order by count_ desc

Column names follow the resource-specific or AzureDiagnostics schema you chose; check your workspace. The errorInfo value tells you most of the story:

errorInfo Likely cause Fix
OriginCertificateNameMismatch / cert errors Origin certificate does not match the origin host header Fix the origin host header or the certificate SAN
OriginConnectionRefused / timeouts Origin firewall blocks Front Door, or the app is down Allow the AzureFrontDoor.Backend service tag, check app
NoHealthyOrigin-style errors Every origin failed health probes Step 3
OriginInvalidResponse Origin sends a malformed or oversized response Check app logs and response headers

3. Fix health probes

az afd origin-group show -g rg-edge --profile-name afd-prod --origin-group-name og-web \
  --query "healthProbeSettings"
az afd origin list -g rg-edge --profile-name afd-prod --origin-group-name og-web \
  --query "[].{name:name, host:hostName, hostHeader:originHostHeader, enabled:enabledState}" -o table

Common mistakes after a change:

  • The probe path (for example /health) now needs authentication or redirects to a login page. Probes need a 200.
  • The probe method is HEAD but the app returns 405 for HEAD. Switch to GET:
az afd origin-group update -g rg-edge --profile-name afd-prod --origin-group-name og-web \
  --probe-request-type GET --probe-path /health --probe-protocol Https --probe-interval-in-seconds 30

Tip

If there is only one origin in the group, you can disable health probes on the origin group. Front Door then always sends traffic to it, which removes probe failures as a cause during the incident.

4. Fix the host header and certificate match

Front Door validates the origin certificate against the origin host header. For App Service and most PaaS origins the host header must equal the origin host name unless you have bound a custom domain on the origin.

az afd origin update -g rg-edge --profile-name afd-prod --origin-group-name og-web \
  --origin-name app-prod --origin-host-header app-prod.azurewebsites.net

If the origin was moved to a certificate that does not include that name, either restore the certificate or temporarily turn off certificate subject name check on the origin (--enforce-certificate-name-check false) while you fix it, and turn it back on afterwards.

Warning

Turning off the name check weakens the origin TLS validation. Record it in the incident and revert it the same day.

With Premium and a Private Link origin, each origin creates a private endpoint connection on the target that must be Approved. A redeploy of the origin or the target can leave it Pending.

az network private-endpoint-connection list --id <origin-resource-id> \
  --query "[].{name:name, status:properties.privateLinkServiceConnectionState.status}" -o table

az network private-endpoint-connection approve --id <connection-id> --description "AFD origin"

6. Origin firewall

If the origin has access restrictions, allow only Front Door with the service tag and check the X-Azure-FDID header against your profile ID:

az afd profile show -g rg-edge --profile-name afd-prod --query frontDoorId -o tsv
az webapp config access-restriction add -g rg-app -n app-prod --priority 100 \
  --service-tag AzureFrontDoor.Backend --http-header x-azure-fdid=<front-door-id>

A wrong or old FDID value after a profile rebuild is a frequent cause of 403/502 at the edge.

Prevent it next time

  • Keep a dedicated anonymous /health endpoint that checks dependencies lightly and always returns 200 when the app can serve.
  • Alert on origin health percentage and on 5xx rate from the Front Door metrics, not just on origin metrics.
  • Treat certificate renewals on origins as a Front Door change and test through the edge before closing the change.
  • Store Front Door config as code (Bicep/Terraform) so you can diff and roll back a bad change.

Related fixes