Skip to content

Troubleshooting

Fast Triage Commands

RG="rg-myapp"
APP_NAME="ca-myapp"

az containerapp show --name "$APP_NAME" --resource-group "$RG" --query properties.provisioningState
az containerapp revision list --name "$APP_NAME" --resource-group "$RG"
az containerapp logs show --name "$APP_NAME" --resource-group "$RG" --type system
az containerapp logs show --name "$APP_NAME" --resource-group "$RG" --type console --follow

Use APP_NAME="ca-myapp" for the examples below. Real observed healthy outputs:

$ az containerapp show --name "$APP_NAME" --resource-group "$RG" --query properties.provisioningState
"Succeeded"

$ az containerapp revision list --name "$APP_NAME" --resource-group "$RG" --output table
Name               Active    TrafficWeight    Replicas    HealthState    RunningState
-----------------  --------  ---------------  ----------  -------------  ------------
ca-myapp--0000001  True      100              1           Healthy        Running

flowchart TD
    TRIAGE["Fast Triage Commands"] --> SYM{"First Symptom?"}
    SYM --> S1["Startup and Provisioning"]
    SYM --> S2["Ingress and Networking"]
    SYM --> S3["Scaling and Runtime"]
    SYM --> S4["Identity and Configuration"]
    SYM --> S5["Platform Features"]
    S1 --> PB1["Image Pull / Revision / Container Start / Probe"]
    S2 --> PB2["Ingress / DNS / Service-to-Service"]
    S3 --> PB3["HTTP Scaling / Event Scaler / CrashLoop"]
    S4 --> PB4["Managed Identity / Secret Reference"]
    S5 --> PB5["Dapr / Jobs / Rollback"]

Common Errors

Error message / symptom Likely cause Fix
ImagePullBackOff, unauthorized: authentication required ACR auth/identity not configured Grant AcrPull to Container App managed identity and verify --registry-server
CrashLoopBackOff App exits on startup Check console logs, missing package/env var, verify startup command
ModuleNotFoundError: <module> Dependency missing from image Add package to requirements.txt, rebuild image, redeploy
Address already in use or bind failure Port mismatch Ensure container listens on 0.0.0.0:8000 and ACA --target-port 8000
Health probe failures Probe path/port invalid or app slow to start Align probe port/path with app endpoint; increase startup tolerance
502/504 from ingress No healthy replica, startup timeout, app not listening Validate revision health, startup logs, and target port
URL not reachable Ingress set to internal Set --ingress external or test from inside VNet/environment
Secret value appears unchanged Secret updates create new revision Restart/deploy new revision after az containerapp secret set

Playbook Categories

Use the category that best matches your first confirmed symptom.

Startup and Provisioning

Ingress and Networking

Scaling and Runtime

Identity and Configuration

Platform Features

How to Use This Hub

  1. Run the fast triage commands to identify the first concrete failure signal.
  2. Open the matching playbook and work through hypotheses and evidence collection.
  3. Use KQL Queries for timeline and correlation.
  4. If multiple signals conflict, use the Detector Map.

See Also