1# AZD Errors
2 
3## Deployment Runtime Errors
4 
5These errors occur **during** `azd up` execution:
6 
7| Error | Cause | Resolution |
8|-------|-------|------------|
9| `unknown flag: --location` | `azd up` doesn't accept `--location` | Use `azd env set AZURE_LOCATION <region>` before `azd up` |
10| Provision failed | Bicep template errors | Check detailed error in output |
11| Deploy failed | Build or Docker errors | Check build logs |
12| Package failed | Missing Dockerfile or deps | Verify Dockerfile exists and dependencies |
13| Quota exceeded | Subscription limits | Request increase or change region |
14| `PrincipalId '...' has type 'ServicePrincipal', which is different from specified PrincipalType 'User'` | Base template RBAC assigns roles with `principalType: 'User'` but deploying identity is a service principal (CI/CD) | Set `allowUserIdentityPrincipal: false` in the `storageEndpointConfig` variable in `infra/main.bicep`. Do NOT try clearing `AZURE_PRINCIPAL_ID` — azd repopulates it. See [Principal Type Mismatch](#principal-type-mismatch). |
15| `ImagePullBackOff` or `azd up` hangs during provision for Container Apps | Container App references an image that doesn't exist in ACR yet | See [Container Apps Bootstrap Problem](#container-apps-bootstrap-problem) |
16| `unauthorized: authentication required` on `docker push` to ACR | ACR auth token expired or scoped incorrectly | See [ACR Authentication Failures](#acr-authentication-failures) |
17| `could not determine container registry endpoint` | Missing `AZURE_CONTAINER_REGISTRY_ENDPOINT` | See [Missing Container Registry Variables](#missing-container-registry-variables) |
18| `map has no entry for key "AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID"` | Missing managed identity env vars | See [Missing Container Registry Variables](#missing-container-registry-variables) |
19| `map has no entry for key "MANAGED_IDENTITY_CLIENT_ID"` | Missing managed identity client ID | See [Missing Container Registry Variables](#missing-container-registry-variables) |
20| `Operation expired` / revision creation timeout (900s) | RBAC propagation delay — Container App's managed identity doesn't have `AcrPull` on ACR yet | See [Container App Revision Timeout](#container-app-revision-timeout) |
21| `found '2' resources tagged with 'azd-service-name: <name>'` | Previous deployment left duplicate-tagged resources in same RG | **Preferred**: Create fresh env with `azd env new <new-name> --no-prompt`, set subscription/location, redeploy. **Alternative**: Delete conflicting resources (requires `ask_user`). |
22| Literal `{{ .Env.* }}` in Terraform errors | azd does not interpolate template variables in `.tfvars.json` | See [Unresolved Terraform Template Variables](#unresolved-terraform-template-variables) |
23 
24> ℹ️ **Pre-flight validation**: Run `azure-validate` before deployment to catch configuration errors early. See [Pre-Deploy Checklist](../../pre-deploy-checklist.md).
25 
26## Container App Revision Timeout
27 
28**Symptom:** `azd up` provisions infrastructure successfully but the Container App revision creation times out after ~900 seconds. The Container App enters a `Failed` provisioning state with no active revision. The `azd` output shows `Operation expired` or `The operation did not complete within the permitted time`.
29 
30**Cause:** Azure RBAC propagation delay. When `azd up` runs both `azd provision` and `azd deploy` in a single step:
311. Bicep creates the Container App with a system-assigned managed identity and a public placeholder image
322. Bicep creates an `AcrPull` role assignment for that identity on ACR in a separate module using the two-phase deployment pattern
333. `azd deploy` immediately pushes the real image and creates a new Container App revision
344. The revision tries to pull the image from ACR, but the `AcrPull` role assignment hasn't propagated yet (can take 1–5 minutes)
355. The image pull fails repeatedly until the 900-second timeout is reached
36 
37**Solution:**
38 
391. **Verify the Container App state:**
40```bash
41az containerapp show --name <app-name> --resource-group <resource-group> \
42  --query "{provisioningState:properties.provisioningState, latestRevision:properties.latestRevisionName}" -o json
43```
44 
452. **Confirm the AcrPull role exists (it may have propagated by now):**
46```bash
47PRINCIPAL_ID=$(az containerapp identity show --name <app-name> --resource-group <resource-group> --query principalId -o tsv)
48az role assignment list --scope $(az acr show --name <acr-name> --resource-group <resource-group> --query id -o tsv) \
49  --assignee-object-id "$PRINCIPAL_ID" --query "[].roleDefinitionName" -o tsv
50```
51 
52**PowerShell:**
53```powershell
54$PrincipalId = az containerapp identity show --name <app-name> --resource-group <resource-group> --query principalId -o tsv
55$AcrScope = az acr show --name <acr-name> --resource-group <resource-group> --query id -o tsv
56az role assignment list --scope $AcrScope --assignee-object-id $PrincipalId --query "[].roleDefinitionName" -o tsv
57```
58 
593. **If AcrPull is missing, assign it:**
60```bash
61az role assignment create \
62  --assignee-object-id "$PRINCIPAL_ID" \
63  --assignee-principal-type ServicePrincipal \
64  --role AcrPull \
65  --scope $(az acr show --name <acr-name> --resource-group <resource-group> --query id -o tsv)
66```
67 
68**PowerShell:**
69```powershell
70$AcrScope = az acr show --name <acr-name> --resource-group <resource-group> --query id -o tsv
71az role assignment create `
72  --assignee-object-id $PrincipalId `
73  --assignee-principal-type ServicePrincipal `
74  --role AcrPull `
75  --scope $AcrScope
76```
77 
784. **Wait for propagation, then redeploy:**
79```bash
80azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT $(az acr show --name <acr-name> --resource-group <resource-group> --query loginServer -o tsv)
81 
82for attempt in 1 2 3 4 5; do
83  echo "Waiting for RBAC propagation (attempt $attempt/5)..."
84  sleep 60
85 
86  if azd deploy --no-prompt; then
87    echo "Deployment succeeded after RBAC propagation."
88    break
89  fi
90 
91  if [ "$attempt" -eq 5 ]; then
92    echo "Deployment still failing after 5 minutes. Re-check AcrPull assignment and Container App revision status."
93    exit 1
94  fi
95done
96```
97 
98**PowerShell:**
99```powershell
100azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT (az acr show --name <acr-name> --resource-group <resource-group> --query loginServer -o tsv)
101 
102for ($attempt = 1; $attempt -le 5; $attempt++) {
103    Write-Output "Waiting for RBAC propagation (attempt $attempt/5)..."
104    Start-Sleep -Seconds 60
105 
106    azd deploy --no-prompt
107    if ($LASTEXITCODE -eq 0) {
108        Write-Output "Deployment succeeded after RBAC propagation."
109        break
110    }
111 
112    if ($attempt -eq 5) {
113        Write-Output "Deployment still failing after 5 minutes. Re-check AcrPull assignment and Container App revision status."
114        exit 1
115    }
116}
117```
118 
119> 💡 **Prevention:** To avoid this in future deployments, ensure the Bicep template includes the `AcrPull` role assignment with `principalType: 'ServicePrincipal'`, and consider using `azd provision` + `azd deploy` as separate steps instead of `azd up` to allow RBAC propagation time between infrastructure creation and app deployment.
120 
121## Container Apps Bootstrap Problem
122 
123**Symptom:** `azd up` hangs or fails during provisioning with `ImagePullBackOff`, or the Container App cannot start because the referenced image doesn't exist in ACR yet.
124 
125**Cause:** The Bicep template creates the Container App referencing an ACR image, but that image doesn't exist until `azd deploy` builds and pushes it. This chicken-and-egg problem blocks provisioning.
126 
127**Solution — use two-phase deployment:**
128 
129```bash
130# Phase 1: Provision infrastructure (Container App uses placeholder image)
131azd provision --no-prompt
132 
133# Phase 2: Build, push, and update Container App with real image
134azd deploy --no-prompt
135```
136 
137> ⚠️ This requires the Bicep template to use a placeholder image parameter (e.g., `mcr.microsoft.com/azuredocs/containerapps-helloworld:latest`) so provisioning succeeds without the app image. If the Bicep hardcodes the ACR image reference, update it to accept a `containerImageName` parameter with a placeholder default before provisioning.
138 
139> ⚠️ Do **NOT** repeatedly poll a hanging `azd up` — if there is no provisioning progress or you continue to see `ImagePullBackOff` events for several minutes during a Container Apps deployment, stop it and switch to the two-phase approach above.
140 
141## ACR Authentication Failures
142 
143**Symptom:** `docker push` fails with `unauthorized: authentication required` even after `az acr login` succeeds.
144 
145**Solution — try these methods in order:**
146 
147```bash
148# Method 1: AAD-based login (preferred)
149az acr login --name <acr-name>
150docker push <acr-name>.azurecr.io/<image>:<tag>
151 
152# Method 2: Admin credentials (fallback)
153ACR_USER=$(az acr credential show --name <acr-name> --query username -o tsv)
154ACR_PASS=$(az acr credential show --name <acr-name> --query "passwords[0].value" -o tsv)
155docker login <acr-name>.azurecr.io -u "$ACR_USER" -p "$ACR_PASS"
156docker push <acr-name>.azurecr.io/<image>:<tag>
157```
158 
159**PowerShell (Method 2):**
160```powershell
161$AcrUser = az acr credential show --name <acr-name> --query username -o tsv
162$AcrPass = az acr credential show --name <acr-name> --query "passwords[0].value" -o tsv
163docker login <acr-name>.azurecr.io -u $AcrUser -p $AcrPass
164docker push <acr-name>.azurecr.io/<image>:<tag>
165```
166 
167> 💡 **Tip:** Prefer `azd deploy` over manual `docker push` — azd handles ACR authentication automatically.
168 
169## Missing Container Registry Variables
170 
171**Symptom:** Errors during `azd deploy` about missing container registry or managed identity environment variables:
172 
173```
174ERROR: could not determine container registry endpoint, ensure 'registry' has been set in the docker options or 'AZURE_CONTAINER_REGISTRY_ENDPOINT' environment variable has been set
175```
176 
177Or:
178 
179```
180ERROR: failed executing template file: template: manifest template:6:14: executing "manifest template" at <.Env.AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID>: map has no entry for key "AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID"
181```
182 
183Or:
184 
185```
186ERROR: failed executing template file: template: manifest template:39:26: executing "manifest template" at <.Env.MANAGED_IDENTITY_CLIENT_ID>: map has no entry for key "MANAGED_IDENTITY_CLIENT_ID"
187```
188 
189**Cause:** This typically occurs with .NET Aspire projects using azd "limited mode" (in-memory infrastructure generation without explicit `infra/` folder). The `azd provision` command creates the Azure Container Registry and Managed Identity resources but doesn't automatically populate the environment variables that `azd deploy` needs to reference them.
190 
191> ⚠️ **Prevention is Better:** For .NET Aspire projects, this issue should be addressed PROACTIVELY before deployment by setting up environment variables after `azd init` but before `azd up`. This avoids deployment failures entirely.
192 
193**Solution:**
194 
195After `azd provision` succeeds, manually set the missing environment variables by querying the provisioned resources:
196 
197```bash
198# Get the resource group name (typically rg-{environment-name})
199azd env get-values
200 
201# Set container registry endpoint
202azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT $(az acr list --resource-group <resource-group-name> --query "[0].loginServer" -o tsv)
203 
204# Set managed identity resource ID
205azd env set AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID $(az identity list --resource-group <resource-group-name> --query "[0].id" -o tsv)
206 
207# Set managed identity client ID
208azd env set MANAGED_IDENTITY_CLIENT_ID $(az identity list --resource-group <resource-group-name> --query "[0].clientId" -o tsv)
209```
210 
211**PowerShell:**
212```powershell
213# Set container registry endpoint
214azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT (az acr list --resource-group <resource-group-name> --query "[0].loginServer" -o tsv)
215 
216# Set managed identity resource ID
217azd env set AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID (az identity list --resource-group <resource-group-name> --query "[0].id" -o tsv)
218 
219# Set managed identity client ID
220azd env set MANAGED_IDENTITY_CLIENT_ID (az identity list --resource-group <resource-group-name> --query "[0].clientId" -o tsv)
221```
222 
223After setting these variables, retry the deployment:
224```bash
225azd deploy --no-prompt
226```
227 
228> 💡 **Tip:** This issue is specific to Aspire limited mode. Manually setting these environment variables after `azd provision` is the recommended workaround.
229 
230## Unresolved Terraform Template Variables
231 
232**Symptom:** Terraform receives literal Go-style template strings instead of resolved values during `azd provision`:
233 
234```
235Error: Invalid value for variable "environment_name"
236  The value "{{ .Env.AZURE_ENV_NAME }}" is not valid.
237```
238 
239Or Terraform silently uses the literal string, causing resource naming failures, state conflicts, and cascading errors that lead to deployment timeouts.
240 
241**Cause:** azd reads `infra/main.tfvars.json`, substitutes `${VAR}` references using its built-in envsubst, and passes the resolved file to Terraform via `-var-file=`. Go-style `{{ .Env.* }}` variables are only processed in `azure.yaml` and service manifests — they are **NOT** interpolated in `.tfvars.json` or any Terraform variable files. If `azure-prepare` generated a `main.tfvars.json` with Go-style template expressions, those literal strings are passed to Terraform.
242 
243**Solution:**
244 
2451. **Fix the syntax** in `infra/main.tfvars.json` — replace Go-style `{{ .Env.* }}` with `${VAR}`:
246   ```json
247   {
248       "environment_name": "${AZURE_ENV_NAME}",
249       "location": "${AZURE_LOCATION}",
250       "subscription_id": "${AZURE_SUBSCRIPTION_ID}"
251   }
252   ```
253 
2542. **Or use `TF_VAR_*` environment variables** if you don't have `main.tfvars.json`:
255   ```bash
256   azd env set TF_VAR_environment_name "$(azd env get-value AZURE_ENV_NAME)"
257   azd env set TF_VAR_location "$(azd env get-value AZURE_LOCATION)"
258   azd env set TF_VAR_subscription_id "$(azd env get-value AZURE_SUBSCRIPTION_ID)"
259   ```
260 
2613. **Ensure `variables.tf`** declares all required variables:
262   ```hcl
263   variable "environment_name" { type = string }
264   variable "location" { type = string }
265   ```
266 
2674. **Re-run deployment:**
268   ```bash
269   azd up --no-prompt
270   ```
271 
272> ⚠️ **Prevention:** This issue should be caught by `azure-validate` Step 10 (Template Variable Resolution Check) before deployment. If you encounter it, re-run validation after fixing.
273 
274## Retry
275 
276After fixing the issue:
277```bash
278azd up --no-prompt
279```
280 
281## Principal Type Mismatch
282 
283**Symptom:** `azd up` fails during provisioning with:
284 
285```
286PrincipalId '...' has type 'ServicePrincipal', which is different from specified PrincipalType 'User'
287```
288 
289**Cause:** Many AZD templates (e.g., `functions-quickstart-python-http-azd`) include RBAC role assignments for the deploying user with hardcoded `principalType: 'User'`. This is controlled by an `allowUserIdentityPrincipal` flag in `main.bicep`'s `storageEndpointConfig` variable. When deploying from CI/CD with a service principal, `azd` sets `AZURE_PRINCIPAL_ID` to that service principal's object ID, but the Bicep still tries to create a role assignment with `principalType: 'User'`, causing ARM to reject it.
290 
291**Solution:**
292 
293In `infra/main.bicep`, find the `storageEndpointConfig` variable and set `allowUserIdentityPrincipal` to `false`:
294 
295```bicep
296var storageEndpointConfig = {
297  enableBlob: true
298  enableQueue: false
299  enableTable: false
300  enableFiles: false
301  allowUserIdentityPrincipal: false  // Set to false for service principal deployments
302}
303```
304 
305> ⚠️ **Do NOT** try to fix this by running `azd env set AZURE_PRINCIPAL_ID ""`. The `azd` CLI repopulates this value from the current auth context, so clearing it has no effect.
306 
307## Cleanup (DESTRUCTIVE)
308 
309```bash
310azd down --force --purge
311```
312 
313⚠️ Permanently deletes ALL resources including databases and Key Vaults.
314