App Service errors — app won't start, 502/503, 403 stopped, container pulls, deployment and Key Vault references
Why an App Service app fails to start, serve or deploy — the container start limit and warmup ping, PORT and WEBSITES_PORT, 502/503, "Error 403 - This web app is stopped", host disk full, image pulls from Container Registry, deployments refused with basic authentication off, unresolved Key Vault references, health check removing instances, and invalid setting names — each with cause, check and fix.
markdownreferencev1DHKD-S25Vstage: operatetrust: officialservice: app-serviceinterface: anyApp Service container didn't startWEBSITES_CONTAINER_START_TIME_LIMIT230 secondsrobots933456.txtWEBSITE_WARMUP_PATHWEBSITES_PORTprocess.env.PORTApp Service 502App Service 503Error 403 - This web app is stopped.no space left on device App ServiceDockerApiExceptionmanifest unknown web appclient with IP is not allowed access web app outbound IPunauthorized web app ACRMicrosoft.ContainerRegistry/registries/pull/readbasic authentication disabled 401 deploySCM Basic Auth Publishing CredentialsKey Vault reference not resolvedkeyVaultReferenceIdentityvnetRouteAllEnabled Key Vaulthealth check unhealthy instance removedYou do not have permission to view this directory or pageapp setting name charactersnpm install --production devDependencies
App Service errors
Start with the log stream (az webapp log tail -n <app> -g <rg>) and Diagnose and solve problems in the portal. On Linux, the platform starts your container (built-in or custom), sends a warmup request, and only then routes traffic; most failures are that handshake.
The app doesn't start (Linux)
| Symptom / message | Cause → fix | Check |
|---|---|---|
| Container restarted before it's ready; site shows an error after a few minutes | The app didn't answer the warmup request to /robots933456.txt within the start time limit (WEBSITES_CONTAINER_START_TIME_LIMIT, default 230 seconds per the settings reference, 240 per the FAQ; range up to 1,800). Any status, even 5xx, counts as an answer. Raise the limit, or set WEBSITE_WARMUP_PATH and WEBSITE_WARMUP_STATUSES | Log stream: warmup and start messages |
| Same, app is listening | Port mismatch. Built-in images: listen on process.env.PORT. Custom containers: ports 80 and 8080 are detected; otherwise set WEBSITES_PORT to the port and EXPOSE it | az webapp config appsettings list -n <app> -g <rg> --query "[?name=='WEBSITES_PORT']" |
| Node.js app exits at start | Wrong startup command, a dependency missing in production mode, or a build that never ran. Zip deploy doesn't build unless SCM_DO_BUILD_DURING_DEPLOYMENT=true. Microsoft's Node page says build automation runs both npm install --production and plain npm install (which includes devDependencies): don't rely on either, deploy what npm start needs | az webapp config show -n <app> -g <rg> --query appCommandLine |
no space left on device | Host disk for images is about 15 GB per instance and separate from the plan's /home quota; large images or writes outside /home fill it | Image size; where the app writes files |
Container images from Container Registry
| Message (Docker logs) | Cause → fix |
|---|---|
… unauthorized | Wrong admin credentials in settings, or the managed identity lacks pull permission (Microsoft.ContainerRegistry/registries/pull/read: AcrPull, or Container Registry Repository Reader if the registry is in ABAC mode) |
DockerApiException … manifest unknown: manifest tagged by "<tag>" is not found | The tag doesn't exist: az acr repository show-tags -n <acr> --repository <repo> |
DockerApiException … denied: client with IP '<web-app-outbound-ip>' is not allowed access. … | Registry firewall. Allow the app's outbound IPs, or use VNet integration with a private endpoint on the registry |
More registry errors: reference/container-registry/errors.md.
Serving errors
| Symptom / message | Cause → fix | Check |
|---|---|---|
Error 403 - This web app is stopped. | The app is stopped, its plan hit a resource quota (Free/Shared tiers), or a billing limit disabled it | az webapp show -n <app> -g <rg> --query state |
| 502 or 503 | The app is slow, crashed, out of memory or CPU, or all instances were removed. Scale up or out, use auto-heal, restart; then find the cause in diagnostics | Diagnose and solve problems; CPU and memory metrics |
| An instance drops out of rotation | Health check pings the configured path every minute; an instance failing (non-2xx) for 10 requests is removed and later replaced. A path that needs auth, or calls a slow dependency, takes good instances out | az webapp config show -n <app> -g <rg> --query healthCheckPath |
Windows: You do not have permission to view this directory or page | No web.config for IISNode: deploy with build automation (it generates one) or add one | site/wwwroot in Kudu |
Deployment and settings
| Symptom / message | Cause → fix |
|---|---|
| FTP or a publish-profile deployment returns 401 | Basic auth is disabled (basicPublishingCredentialsPolicies/scm and /ftp). Deploy with Entra ID: az webapp deploy, or GitHub Actions with OIDC (patterns/github-actions-to-azure.md). Existing GitHub workflows that use a publish profile stop working |
| App setting shows Key Vault reference as not resolved | The identity used for references lacks a Key Vault data role (Key Vault Secrets User), the wrong identity is used (set keyVaultReferenceIdentity to the user-assigned identity's resource ID), or the vault's firewall blocks the app. Linux apps (except Flex Consumption) need vnetRouteAllEnabled to reach a vault's private endpoint. Values refresh every 24 hours, or on any config change |
| A setting is rejected or ignored | Names may contain only letters, numbers and underscores: use __ for hierarchy (not :) |
Key Vault access rules: reference/keyvault/access-and-errors.md. Configuration details: reference/app-service/configuration-and-networking.md.