App Service Troubleshooting¶

A hypothesis-driven troubleshooting guide for Azure App Service workloads on Windows and Linux.

What This Is¶

A practical field guide for troubleshooting real-world issues on Azure App Service across its supported hosting modes.

This is not a general Azure tutorial. It is designed to help engineers move from symptom to validated interpretation faster.

How It Works¶

graph TD
    A[Observe Symptom] --> B[List Hypotheses]
    B --> C[Collect Evidence]
    C --> D[Validate / Disprove]
    D --> E[Identify Root Cause]
    E --> F[Mitigate]

Every playbook follows this flow:

1. Start from the symptom — what the engineer actually observes
2. List competing hypotheses — multiple plausible causes
3. Collect evidence — metrics, logs, detectors, configuration
4. Validate or disprove each hypothesis with specific signals
5. Identify the most likely root cause pattern
6. Apply mitigations — immediate and long-term

Start Here¶

Inbound Access and Slow-Request Symptom Routes¶

Choose the observed symptom rather than a presumed cause. These links lead to investigation steps, evidence collection, competing hypotheses, mitigation and prevention. They are not customer RCA records or new lab execution results; check each destination's verification boundary before treating an example as evidence.

For app-to-dependency failures, use Outbound / Network instead. The client-to-app/SCM path is a different investigation. Unavailable observations leave the cause inconclusive; a configuration screenshot alone cannot complete the diagnostic steps.

Quick Decision Tree¶

Use this to route to the right playbook in under 60 seconds:

graph TD
    A[Symptom Observed] --> B{App returns HTTP errors?}
    B -->|503 on all requests| C[Startup Failure]
    B -->|Intermittent 5xx| D[Performance / Load]
    B -->|200 but slow| E[Performance / Cold Start]
    B -->|No errors but wrong behavior| F[Config / Routing]

    C --> C1[Startup Probe Failed?]
    C1 -->|Yes, logs unavailable or empty| C2[Telemetry inconclusive → verify logging and process state]
    C1 -->|Yes, app listening on 127.0.0.1| C3[Wrong bind address → Failed to Forward Request]
    C1 -->|Yes, timeout on port| C4[Port mismatch → Container HTTP Pings]

    D --> D1{Outbound connections involved?}
    D1 -->|Yes, connection timeouts| D2[Measure SNAT, dependency, and worker pressure]
    D1 -->|No, sync worker blocking| D3[Intermittent 5xx Under Load]

    E --> E1{First request after deploy?}
    E1 -->|Yes| E2[Cold Start / Slow Start]
    E1 -->|No, always slow| E3[Memory Pressure or CPU]

    F --> F1{After slot swap?}
    F1 -->|Yes| F2[Slot Swap Config Drift]
    F1 -->|No, DNS/network| F3[DNS VNet Resolution]

    style C fill:#c62828,color:#fff
    style D fill:#ef6c00,color:#fff
    style E fill:#f9a825,color:#000
    style F fill:#1565c0,color:#fff

Hosting Mode: Where to Look First¶

Choose the entry path that matches the app before applying runtime-specific advice:

Different hosting modes have different observation points. Use this table to prioritize your investigation without carrying Windows settings into Linux advice:

Windows Symptom Routes¶

Representative Log Patterns¶

Quick reference for recognizing common failure signatures:

Topics¶

Performance¶

• Tail Latency and Matched Baselines
• Slow Response but Low CPU
• Memory Pressure & Worker Degradation
• Intermittent 5xx Under Load
• No Space Left on Device
• Slow Start / Cold Start
• CORS and Token Errors

Inbound Access / SCM¶

• SCM Client DNS and HTTP Failures
• Private Endpoint and Access Restriction Decisions

Outbound / Network¶

• SNAT or Application Issue?
• DNS Resolution (VNet-Integrated)
• Private Endpoint / Custom DNS Confusion

Startup / Availability¶

• Container Didn't Respond to HTTP Pings
• Warm-up vs Health Check
• Slot Swap Failed During Warm-up
• Deployment Succeeded but Startup Failed
• Failed to Forward Request
• Slot Swap Config Drift
• Auth Redirect Loop

Quick Start¶

Hands-on Labs¶

Deploy reproduction environments to your Azure subscription and observe real symptoms:

• Memory Pressure
• Intermittent 5xx Under Load
• Container HTTP Pings
• SNAT Exhaustion
• DNS Resolution (VNet)
• Private Endpoint Route Fault
• No Space Left on Device
• Deployment Succeeded but Startup Failed
• Failed to Forward Request
• Slot Swap Config Drift
• Slow Start / Cold Start

Architecture & Methodology¶

Portal view: Diagnose and solve problems landing page¶

Purpose: Show the Portal entry point to the App Service detectors.

Look for: The Troubleshooting categories cards, such as Availability and Performance, and the search box.

Expected result: Choose the category that matches the symptom to open its detectors.

The Portal's built-in Diagnose and solve problems blade is the operational entry point that complements the architecture and methodology pages below. Treat it as the first stop during an active incident — Risk alerts surfaces pre-detected critical issues, the seven Troubleshooting categories map directly to the failure classifications in the Mental Model, and the Popular troubleshooting tools (App Down Workflow, Web App Slow) run guided diagnostic flows that consolidate many manual KQL queries.

• Architecture Overview — How App Service components interact during failures
• Decision Tree — Route from symptom to playbook in 60 seconds
• Evidence Map — What evidence to collect for each failure type
• Mental Model — Framework for hypothesis-driven diagnosis
• Troubleshooting Method — Full methodology deep-dive
• Detector Map — Platform diagnostic detectors and what they check

See Also¶

• Architecture Overview
• Decision Tree
• Evidence Map

Sources¶

• Microsoft Learn source 1
• Microsoft Learn source 2