App Service OSS Troubleshooting¶

A hypothesis-driven troubleshooting guide for Azure App Service OSS workloads.

What This Is¶

A practical field guide for troubleshooting real-world issues on Azure App Service Linux.

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¶

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, 0 console logs| C2[Wrong startup command → Deployment Succeeded Startup Failed]
    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[SNAT Exhaustion]
    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¶

Different hosting modes have different observation points. Use this table to prioritize your investigation:

Representative Log Patterns¶

Quick reference for recognizing common failure signatures:

Topics¶

Performance¶

• 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

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)
• 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¶

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