--- cuppy_hub: azure cuppy_path: reference/app-service/errors.md cuppy_section: docs cuppy_doc: DHKD-S25V cuppy_doc_uuid: af564536-2a2d-439b-bdfa-51f465826294 cuppy_permalink: https://cuppy.io/azure/d/DHKD-S25V cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/azure/docs/reference/app-service/errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 7562bdad22e628023be7e25fc9a29aa16230297814cb16c1cb2c7e40aff93c96 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # App Service errors **Start with the log stream** (`az webapp log tail -n -g `) 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 -g --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 -g --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 "" is not found` | The tag doesn't exist: `az acr repository show-tags -n --repository ` | | `DockerApiException … denied: client with 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 -g --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 -g --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`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.