Container Apps Troubleshooting
Common Issues Matrix
| Symptom | Likely Cause | Quick Fix |
|---|---|---|
| Image pull failure | ACR credentials missing | az containerapp registry set --identity system |
| ACR build fails | ACR Tasks disabled (free sub) | Build locally with Docker |
| Cold start timeout | min-replicas=0 | az containerapp update --min-replicas 1 |
| Port mismatch | Wrong target port | Check Dockerfile EXPOSE matches ingress |
| App keeps restarting | Health probe failing | Verify /health endpoint |
Image Pull Failures
Diagnose:
# Check registry configuration
az containerapp show --name APP -g RG --query "properties.configuration.registries"
# Check revision status
az containerapp revision list --name APP -g RG --output tableFix:
az containerapp registry set \
--name APP -g RG \
--server ACR.azurecr.io \
--identity systemACR Tasks Disabled (Free Subscriptions)
Symptom: az acr build fails with "ACR Tasks is not supported"
Fix: Build locally instead:
docker build -t ACR.azurecr.io/myapp:v1 .
az acr login --name ACR
docker push ACR.azurecr.io/myapp:v1Cold Start Issues
Symptom: First request very slow or times out
Fix:
az containerapp update --name APP -g RG --min-replicas 1Health Probe Failures
Symptom: Container keeps restarting
Check:
# View health probe config
az containerapp show --name APP -g RG --query "properties.configuration.ingress"
# Check if /health endpoint responds
curl https://APP.REGION.azurecontainerapps.io/healthFix: Ensure app has health endpoint returning 200:
app.get('/health', (req, res) => res.sendStatus(200));Port Mismatch
Symptom: App starts but returns 502/503
Check:
az containerapp show --name APP -g RG --query "properties.configuration.ingress.targetPort"Verify: App must listen on this exact port. Check:
- Dockerfile
EXPOSEstatement process.env.PORTor hardcoded port in app
View Logs
# Stream logs (wait for replicas if scale-to-zero)
az containerapp logs show --name APP -g RG --follow
# Recent logs
az containerapp logs show --name APP -g RG --tail 100
# System logs (startup issues)
az containerapp logs show --name APP -g RG --type systemGet All Diagnostic Info
Use the containerapp-diagnostics script
(PowerShell) to collect everything in one
call. It prints clearly labeled sections — revisions, registry config, ingress config, and
recent logs — and a summary line describing what it collected. Interpreting the output
remains your job.
..\..\scripts\containerapp-diagnostics.ps1 -Name <app> -ResourceGroup <rg>../../scripts/containerapp-diagnostics.sh --name <app> --resource-group <rg>