CloudForge
Ask

Guided incident tool

Azure App Service 502 Troubleshooter

Answer a few questions about the failure and receive a prioritized, production-aware investigation plan with evidence to collect before making changes.

Free and guest-ready

No sign-in is required. Review every result before using it in a production environment.

Describe the 502 scenario

No subscription access is required.

Capture logs before restarting whenever the incident allows it. A restart can remove evidence without fixing the cause.

Prioritized investigation plan

7 evidence-led steps

  1. 01

    Confirm the failure boundary

    Test the default azurewebsites.net hostname, record the UTC timestamp, status code, response headers, and whether the failure affects every route.

  2. 02

    Capture platform and application evidence

    Collect deployment, application, and platform logs before restarting. Correlate the first 502 response with deployments, configuration changes, scaling, and worker restarts.

    az webapp log tail --resource-group <resource-group> --name <app-name>
  3. 03

    Separate deployment success from runtime startup

    Review the deployment output and then inspect runtime startup independently. Compare the startup command, stack version, app settings, package contents, and dependency availability with the last working release.

    az webapp log deployment list --resource-group <resource-group> --name <app-name> --output table
  4. 04

    Validate the Linux runtime and startup command

    Check the configured stack, startup command, package layout, executable permissions, and application bind address. The application must listen on the platform-provided port.

    az webapp config show --resource-group <resource-group> --name <app-name> --query '{linuxFxVersion:linuxFxVersion,startupCommand:appCommandLine}'
  5. 05

    Check shared configuration and dependencies

    A failure across every instance points toward the deployed artifact, shared application settings, identity, DNS, certificates, network access, or an unavailable downstream dependency.

  6. 06

    Test the smallest reversible recovery action

    Use a slot swap, rollback, configuration reversion, or controlled restart only after identifying the leading hypothesis. Change one variable and retain a rollback path.

  7. 07

    Verify complete recovery

    Confirm representative transactions, dependency calls, instance health, error rate, latency, alerts, and custom-domain routing—not only one successful HTTP response.

Scenario-specific investigation sequence
Linux, Windows, and container guidance
Evidence and command checklist
Safe rollback and verification reminders

What an App Service 502 error means

HTTP 502 indicates that a gateway or front-end component could not obtain a valid response from the application worker or an upstream dependency. The visible status code does not identify the root cause. Common causes include application startup failures, incorrect container ports, unhealthy workers, deployment errors, dependency timeouts, and proxy or routing problems.

Start by defining the failure boundary. Confirm whether the default App Service hostname fails, whether every instance is affected, when the problem began, and whether it followed a deployment or configuration change. This prevents an application failure from being mistaken for an Application Gateway, Front Door, DNS, or network problem.

Evidence to collect before changing production

Collect deployment logs, application logs, container logs, platform diagnostics, health-check state, Application Insights exceptions, and a timestamped reproduction. Compare configuration and application settings with the last known working state. For custom containers, verify that the process remains running and listens on the expected port.

A successful deployment record does not prove that the application started successfully. Deployment and runtime are separate stages. Look for process exits, missing environment variables, module-loading failures, certificate problems, connection failures, and startup timeouts.

  • Test the default azurewebsites.net hostname to isolate upstream routing.
  • Check deployment and restart timestamps against the first 502 response.
  • Review startup commands, stack versions, container ports, and health checks.
  • Use a deployment slot or rollback plan before applying a production change.

Recovering safely from repeated 502 responses

Prefer the smallest reversible action that tests the leading hypothesis. Restarting can restore service temporarily, but it may also remove evidence and conceal a recurring startup problem. Capture logs first whenever the incident allows it.

After recovery, verify more than the HTTP status. Check representative application transactions, dependency calls, instance health, error rates, latency, and monitoring. Record the cause and preventive action so the same deployment or configuration failure is detected earlier next time.

Frequently asked questions

Why does App Service return 502 immediately after deployment?

The new application may be failing during startup, listening on the wrong port, missing configuration, or exceeding a startup timeout. Deployment logs and runtime logs must be checked separately.

Should I restart the App Service first?

A restart can help, but collect available logs and configuration evidence first. Otherwise the restart may remove useful evidence without resolving the underlying problem.

Can an upstream gateway cause the 502?

Yes. Test the default App Service hostname and compare it with Application Gateway, Front Door, or custom-domain behavior to identify the failing boundary.