1# App Service Troubleshooting
2 
3## Common Issues Matrix
4 
5| Symptom | Likely Cause | Action |
6|---------|--------------|-----------|
7| High CPU / memory | Runaway process, inefficient code | Use Process Explorer via Kudu, scale up |
8| Deployment failure | Build error, locked files, quota | Check Kudu logs at `https://APP.scm.azurewebsites.net/api/deployments` to look for details on build errors, locked files or lack of storage quota |
9| App crash / restart | Unhandled exception, OOM kill | Review Event Log and STDERR in Diagnose & Solve |
10| Slow responses | Downstream dependency, no caching | Enable request tracing, check dependency calls |
11| 502 / 503 errors | App not starting, port conflict | Check STDERR logs, verify startup command |
12| TLS / domain errors | Certificate expired, DNS mismatch | `az webapp config ssl list`, verify CNAME |
13| Health check failure | Endpoint not returning 200 | Verify health check path responds within 2 min |
14 
15---
16 
17## High CPU / Memory Diagnosis
18 
19**Diagnose:**
20```bash
21# Check app metrics
22az monitor metrics list --resource APP_RESOURCE_ID \
23  --metric "CpuPercentage,MemoryPercentage" --interval PT1M --output table
24 
25# View running processes via ARM Processes API (Entra ID auth)
26az rest --method get \
27  --uri "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/processes?api-version=2024-04-01"
28```
29 
30**Fix:** Scale up (`az appservice plan update -n <app-service-plan-name> -g <resource-group> --sku P1V3`) or profile the app via Kudu Process Explorer at `https://APP.scm.azurewebsites.net/ProcessExplorer/` to identify hot paths.
31 
32---
33 
34## Deployment Failure Analysis
35 
36**Diagnose:**
37```bash
38# List deployment history
39az webapp deployment list -n APP -g RG --output table
40 
41# View deployment log for a specific deployment
42az webapp log deployment show -n APP -g RG --deployment-id DEPLOY_ID
43 
44# Stream build logs from Kudu
45az webapp log tail -n APP -g RG
46```
47 
48**KQL — Failed deployments:**
49```kql
50// Replace <app-service-resource-id> with the full resource ID, for example:
51// /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>
52AppServicePlatformLogs
53| where TimeGenerated > ago(24h)
54| where Level == "Error" and _ResourceId == "<app-service-resource-id>"
55| project TimeGenerated, Level, Message
56| order by TimeGenerated desc
57```
58 
59**Common deployment failures:**
60 
61| Error Message | Cause | Fix |
62|---------------|-------|-----|
63| `WEBSITE_RUN_FROM_PACKAGE=1` but no package | Missing zip deploy artifact | Redeploy with `az webapp deploy --src-path app.zip` |
64| `Error building on server` | Oryx build failure | Check build logs, pin runtime version |
65| `Locked file` during deploy | Files in use | Set an environment variable named `MSDEPLOY_RENAME_LOCKED_FILES=1` on the App Service resource to enable MSDeploy to rename locked files. |
66 
67---
68 
69## Application Crash / Restart Diagnosis
70 
71**Diagnose:**
72```bash
73# Check recent restarts via activity log
74az monitor activity-log list -g RG --resource-id APP_RESOURCE_ID \
75  --max-events 10 --query "[?operationName.value=='Microsoft.Web/sites/restart/action']"
76 
77# View STDERR/STDOUT (Linux)
78az webapp log download -n APP -g RG --log-file logs.zip
79```
80 
81**KQL — App crashes and errors:**
82```kql
83AppServiceConsoleLogs
84| where TimeGenerated > ago(1h)
85| where ResultDescription contains "error" or ResultDescription contains "fatal"
86| project TimeGenerated, ResultDescription
87| order by TimeGenerated desc
88| take 50
89```
90 
91**Health check failures:**
92```bash
93# Show health check config
94az webapp show -n APP -g RG --query "siteConfig.healthCheckPath"
95 
96# Test the endpoint directly
97curl -s -o /dev/null -w "%{http_code}" https://APP.azurewebsites.net/health
98```
99 
100> ⚠️ **Warning:** If the health check fails on >50% of instances for 1 hour, the instance is replaced.
101 
102---
103 
104## Slow Response Time Investigation
105 
106**Diagnose:**
107```bash
108# Check average response time
109az monitor metrics list --resource APP_RESOURCE_ID \
110  --metric "HttpResponseTime" --interval PT5M --aggregation Average --output table
111 
112# Enable failed request tracing
113az webapp log config -n APP -g RG --failed-request-tracing true
114```
115 
116**KQL — Slow requests with dependency analysis:**
117```kql
118AppServiceHTTPLogs
119| where TimeGenerated > ago(1h)
120| where TimeTaken > 5000
121| project TimeGenerated, CsUriStem, ScStatus, TimeTaken, CsHost
122| order by TimeTaken desc
123| take 20
124```
125 
126**Auto-Heal — Automatic mitigation:**
127```bash
128# Configure auto-heal to recycle on slow requests
129az webapp config set -n APP -g RG \
130  --auto-heal-enabled true \
131  --generic-configurations '{"autoHealRules":{"triggers":{"slowRequests":{"timeTaken":"00:00:30","count":10,"timeInterval":"00:02:00"}},"actions":{"actionType":"Recycle"}}}'
132```
133 
134---
135 
136## Custom Domain / TLS Certificate Issues
137 
138**Diagnose:**
139```bash
140# List custom domains
141az webapp config hostname list -g RG --webapp-name APP --output table
142 
143# List TLS certificates
144az webapp config ssl list -g RG --output table
145 
146# Check SSL binding
147az webapp config ssl show --certificate-name CERT -g RG
148```
149 
150| Symptom | Cause | Fix |
151|---------|-------|-----|
152| `ERR_CERT_DATE_INVALID` | Certificate expired | If certificate came from an external certificate authority, renew with `az webapp config ssl upload` and upload a new certificate or enable managed certificates to allow Azure to provide a free TLS/SSL certificate |
153| `DNS_PROBE_FINISHED_NXDOMAIN` | CNAME not configured | Add CNAME record pointing to `APP.azurewebsites.net` |
154| `SSL binding not found` | Missing SNI binding | Add the missing SNI binding using `az webapp config ssl bind --certificate-thumbprint THUMB --ssl-type SNI -n APP -g RG` |
155| Managed cert pending | DNS validation incomplete | Verify TXT record `asuid.DOMAIN` matches custom domain verification ID |
156 
157---
158 
159## AZ CLI or MCP Tools for App Service Diagnostics
160 
161| Tool | Command | Use When |
162|----------|---------|----------|
163| `Azure CLI` | `az webapp list` | List all web apps in subscription |
164| `Azure CLI` | `az webapp show -n APP -g RG` | Get app config, stack, status |
165| `Azure CLI` | `az webapp config appsettings list -n APP -g RG` | Check env vars and connection strings |
166| `Azure CLI` | `az webapp deployment slot list -n APP -g RG` | Compare slot configurations |
167| `mcp_azure_mcp_appservice` | `appservice_webapp_diagnostic_diagnose` | AI-powered root cause analysis |
168| `mcp_azure_mcp_monitor` | `monitor_resource_log_query` | Run KQL against Log Analytics |
169| `mcp_azure_mcp_resourcehealth` | `get` | Check platform-level health status |
170 
171> 💡 **Tip:** Start with `mcp_azure_mcp_appservice` (`diagnose`) — it automatically runs relevant detectors and surfaces the most likely root cause before you dig into logs manually.
172 
173---
174 
175## Combined Diagnostic Script
176 
177```bash
178echo "=== App Service Diagnostics ===" && \
179echo "App Config:" && az webapp show -n APP -g RG --query "{state:state, runtime:siteConfig.linuxFxVersion, healthCheck:siteConfig.healthCheckPath, alwaysOn:siteConfig.alwaysOn}" -o table && \
180echo "Recent Deployments:" && az webapp deployment list -n APP -g RG --query "[:3].{id:id, status:status, time:end_time}" -o table && \
181echo "App Settings:" && az webapp config appsettings list -n APP -g RG --query "[].name" -o tsv && \
182echo "Custom Domains:" && az webapp config hostname list -g RG --webapp-name APP -o table
183```
184