Troubleshooting¶

Platform-level troubleshooting reference for Azure App Service across runtimes.

Overview¶

flowchart TD
    A[Incident Symptom] --> B[Collect Baseline]
    B --> C{Issue Domain}
    C --> D[Deployment Checks]
    C --> E[Network Checks]
    C --> F[Runtime and Logs]
    D --> G[Validate and Mitigate]
    E --> G
    F --> G

Diagnostic Tools Overview¶

Fast Triage Commands¶

az webapp show --resource-group $RG --name $APP_NAME --output table
az webapp log tail --resource-group $RG --name $APP_NAME
az webapp config appsettings list --resource-group $RG --name $APP_NAME --output table
az webapp deployment slot list --resource-group $RG --name $APP_NAME --output table

Note: az webapp log tail may not work reliably for Linux App Service. Use the Azure Portal Log stream or /home/LogFiles as alternatives.

Common Platform Issues¶

Deployment Troubleshooting¶

Check deployment history¶

az webapp log deployment list \
  --resource-group $RG \
  --name $APP_NAME \
  --output table

Check latest deployment details¶

az webapp log deployment show \
  --resource-group $RG \
  --name $APP_NAME \
  --deployment-id latest \
  --output json

Validate build-on-deploy setting¶

az webapp config appsettings list \
  --resource-group $RG \
  --name $APP_NAME \
  --query "[?name=='SCM_DO_BUILD_DURING_DEPLOYMENT']"

Networking Troubleshooting¶

VNet integration status¶

az webapp vnet-integration list \
  --resource-group $RG \
  --name $APP_NAME \
  --output table

Route-all check¶

az webapp config appsettings list \
  --resource-group $RG \
  --name $APP_NAME \
  --query "[?name=='WEBSITE_VNET_ROUTE_ALL']"

This reads only the legacy app setting. A site can declare routing through the outboundVnetRouting properties instead, so an empty result here does not mean route-all is off; see Outbound VNet routing properties for how to inspect them.

Set route-all when required:

az webapp config appsettings set \
  --resource-group $RG \
  --name $APP_NAME \
  --settings WEBSITE_VNET_ROUTE_ALL=1

The legacy setting is still supported. Microsoft Learn recommends the outboundVnetRouting.allTraffic property; see Outbound VNet routing properties.

Outbound IP allowlist checks¶

az webapp show \
  --resource-group $RG \
  --name $APP_NAME \
  --query "{outbound: outboundIpAddresses, possible: possibleOutboundIpAddresses}" \
  --output json

Kudu-Based Checks¶

• Open Kudu: https://${APP_NAME}.scm.azurewebsites.net
• Check environment: /api/environment
• Check running processes: /api/processes
• Review logs under /home/LogFiles

For Linux custom containers, use those Kudu checks mainly for deployment context, environment snapshots, and shared logs. Do not assume /api/processes or Kudu file browsing reflects the main app container runtime state.

See Kudu API Reference for endpoint details.

Data to Collect Before Escalation¶

• UTC time window and affected endpoint(s)
• Correlation/operation ID (if available)
• Recent deployment ID and timestamp
• Plan SKU and current instance count
• Relevant error snippets (PII removed)

See Also¶

• KQL Queries
• Kudu Queries

Sources¶

• Diagnose and Solve Problems in App Service (Microsoft Learn)
• Troubleshoot Diagnostic Logs in App Service (Microsoft Learn)
• Networking Features in App Service (Microsoft Learn)

Language-Specific Details¶

Runtime-specific startup failures, package/import issues, framework worker tuning, and language-level exception handling are documented in:

• Azure App Service Node.js Guide — Troubleshooting
• Azure App Service Python Guide — Troubleshooting