Module 17: Troubleshooting & Debugging

"Deployments fail — that's normal. What separates smooth teams is knowing how to read the error and fix it fast."

Level: Beginner · Time: ~2 days · Prerequisites: Modules 8, 16

Learning Objectives

By the end of this module, you will be able to:

• Diagnose common azd deployment failures
• Use logs and verbose output to find causes
• Fix provisioning vs deployment errors
• Debug AI-specific issues

1. A Calm Approach to Errors

A failed azd up isn't a disaster — it's information. Deployments touch many systems — your code, Azure's APIs, quotas, networks — so some friction is normal even for experts. The trick is to read the actual error message, identify whether it's a provisioning or deployment problem, and fix that specific thing. Panic and random retries waste time; reading the message solves it. Azure output can be verbose, but the useful part is usually a short code and one sentence near the top — scroll up to the first failure, not the last.

2. Provisioning vs Deployment Failures

Where in the azd up sequence it broke tells you where to look — provisioning runs first (creating Azure resources), then deployment (building and pushing your code):

3. Turn On the Detail

When the message isn't enough, ask azd for more:

azd up --debug

The --debug flag prints verbose logs showing exactly what azd ran, which Azure calls it made, and where it stopped. Redirect it to a file (azd up --debug > deploy.log 2>&1) when the output scrolls past your terminal's buffer. For app-level issues — the deploy succeeded but the app misbehaves — the error won't be in azd at all: check the host's logs (Container Apps / App Service logs) or your Application Insights exceptions (Module 16).

4. Common Fixes

A handful of issues cover the large majority of failures — work down this list before assuming anything exotic:

• Not logged in / wrong subscription → azd auth login, check azd env.
• Quota exceeded → request more, or lower the SKU/capacity (Module 15).
• Region/model unavailable → pick a supported region.
• App won't start → check it reads the right port and env vars (Module 6).

When none of these fit, widen the net: copy the exact error code into the azd or Azure docs — someone has almost certainly hit it before, and the fix is often one setting away.

5. Debugging AI Apps

AI apps add their own puzzles: a model returns errors (check the deployment name and endpoint), responses are slow or throttled (check capacity/TPM from Module 15), or answers are wrong (check the prompt, the data, and whether RAG retrieved anything at all). A 404 usually means the deployment name is misspelled; a 429 means you've hit your token quota. Application Insights and the Foundry portal are your windows into these.

✅ Checkpoint

1. What's the first thing to do when a deploy fails?
2. How do you tell a provisioning failure from a deployment failure?
3. What flag makes azd print verbose logs?

Answers: 1) Read the actual error message and identify the specific cause. 2) Ask whether it failed while creating resources (provision) or pushing code (deploy). 3) --debug.

Further Learning

• Troubleshoot azd
• Container Apps logging

Part of "AZD for Beginners." Adapted from Microsoft's open AZD curriculum (MIT License).