1# Troubleshooting
2 
3This reference covers common errors encountered during Azure deployment with `azd` and how to resolve them.
4 
5## Language Not Supported
6 
7**Symptom:** Error message like `ERROR: error executing step command 'package --all': initializing service 'web', getting framework service: language 'html' is not supported by built-in framework services`
8 
9**Cause:** Using unsupported language value in `azure.yaml`. Neither `html` nor `static` are valid language types for azd.
10 
11**Solution:**
12 
13For pure HTML/CSS static sites, omit the `language` field:
14 
15```yaml
16services:
17  web:
18    project: ./src/web   # or . for root
19    host: staticwebapp
20    dist: .              # relative to project path (only works when project != root)
21```
22 
23Valid language values: `python`, `js`, `ts`, `java`, `dotnet`, `go` (or omit for staticwebapp without build)
24 
25## SWA Project Path Issues
26 
27**Symptom:** Deployment fails, gets stuck in "Uploading", or shows default Azure page
28 
29**Cause:** Incorrect `project` or `dist` configuration.
30 
31**Solution:** Match configuration to your project layout:
32 
33| Layout | `project` | `dist` |
34|--------|-----------|--------|
35| Static files in root | `.` | `public` (put files in public/ folder) |
36| Framework in root | `.` | `dist`/`build`/`out` |
37| Static in subfolder | `./src/web` | `.` |
38| Framework in subfolder | `./src/web` | `dist`/`build`/`out` |
39 
40> **SWA CLI Limitation:** When `project: .`, you **cannot** use `dist: .`. Put static files in a `public/` folder instead.
41 
42## SWA Dist Not Found
43 
44**Symptom:** Error like `dist folder not found` or empty deployment
45 
46**Cause:** The `dist` path doesn't exist or build didn't run.
47 
48**Solution:**
491. For framework apps: ensure `language: js` is set to trigger build
502. Verify `dist` value matches your framework's output folder
513. For pure static in root: put files in `public/` folder and use `dist: public`
524. For pure static in subfolder: use `dist: .`
53 
54## Service Resource Not Found
55 
56**Symptom:** Error message like `ERROR: getting target resource: resource not found: unable to find a resource tagged with 'azd-service-name: web'`
57 
58**Cause:** The Azure resource is missing the `azd-service-name` tag that azd uses to link services defined in `azure.yaml` to deployed infrastructure.
59 
60**Solution:**
61 
62Add the tag to your bicep resource definition:
63 
64```bicep
65resource staticWebApp 'Microsoft.Web/staticSites@2022-09-01' = {
66  name: name
67  location: location
68  tags: union(tags, { 'azd-service-name': 'web' })  // Must match service name in azure.yaml
69  // ... rest of config
70}
71```
72 
73After updating, run `azd provision` to apply the tag, then `azd deploy`.
74 
75## Location Not Available for Resource Type
76 
77**Symptom:** Error message like `LocationNotAvailableForResourceType: The provided location 'westus3' is not available for resource type 'Microsoft.Web/staticSites'`
78 
79**Cause:** Azure Static Web Apps is not available in all regions.
80 
81**Solution:**
82 
83Change to a supported region:
84 
85```bash
86azd env set AZURE_LOCATION westus2
87```
88 
89Available regions for Static Web Apps: `westus2`, `centralus`, `eastus2`, `westeurope`, `eastasia`
90 
91## Missing Infrastructure Parameters
92 
93**Symptom:** Error message like `ERROR: prompting for value: no default response for prompt 'Enter a value for the '<param>' infrastructure parameter:'`
94 
95**Cause:** A Bicep parameter exists in your template but no corresponding environment variable is set.
96 
97**Example:** The `infra/main.bicep` has a parameter like:
98```bicep
99@description('SKU for the storage account.')
100param storageAccountSku string
101```
102 
103**Solution:**
104 
1051. Check `infra/main.parameters.json` for an existing mapping to this parameter.
106 
1072. **If a mapping exists** (e.g., `"value": "${STORAGE_SKU}"`), ask the user for the desired value and set the environment variable:
108```bash
109azd env set STORAGE_SKU <user-provided-value>
110```
111 
1123. **If no mapping exists**, add one to `infra/main.parameters.json`:
113```json
114{
115  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
116  "contentVersion": "1.0.0.0",
117  "parameters": {
118    "storageAccountSku": {
119      "value": "${STORAGE_SKU}"
120    }
121  }
122}
123```
124 
125> ⚠️ **Warning:** `main.parameters.json` uses ARM JSON syntax. Do **not** use `.bicepparam` syntax (`using`, `param`, `readEnvironmentVariable()`) in this file — `azd` will fail with a JSON parse error.
126 
127Then ask the user for the desired value and set the environment variable:
128```bash
129azd env set STORAGE_SKU <user-provided-value>
130```
131 
132During `azd provision`, azd will substitute `${STORAGE_SKU}` with the value from the environment and will pass it to Bicep.
133 
134**Reference:** [Use environment variables in infrastructure files](https://learn.microsoft.com/azure/developer/azure-developer-cli/manage-environment-variables?tabs=bash#use-environment-variables-in-infrastructure-files)
135 
136## .NET Aspire Limited Mode - Missing Environment Variables
137 
138**Symptom:** When deploying .NET Aspire projects with azd, `azd provision` succeeds but `azd deploy` fails with errors about missing container registry or managed identity environment variables.
139 
140**Cause:** .NET Aspire projects can use azd in "limited mode" where infrastructure is generated in-memory without creating an explicit `infra/` folder on disk. In this mode, `azd provision` creates Azure resources (Container Registry, Managed Identity, Container Apps Environment, etc.) but doesn't automatically populate certain environment variables that `azd deploy` needs.
141 
142**Common missing variables:**
143- `AZURE_CONTAINER_REGISTRY_ENDPOINT` — ACR login server URL
144- `AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID` — Managed identity resource ID
145- `MANAGED_IDENTITY_CLIENT_ID` — Managed identity client ID
146 
147**Solution:**
148 
149After `azd provision` completes, manually populate the missing environment variables:
150 
151```bash
152# Get your resource group name first
153azd env get-values
154 
155# Set the container registry endpoint
156azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT $(az acr list --resource-group <resource-group-name> --query "[0].loginServer" -o tsv)
157 
158# Set the managed identity resource ID
159azd env set AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID $(az identity list --resource-group <resource-group-name> --query "[0].id" -o tsv)
160 
161# Set the managed identity client ID
162azd env set MANAGED_IDENTITY_CLIENT_ID $(az identity list --resource-group <resource-group-name> --query "[0].clientId" -o tsv)
163```
164 
165**PowerShell:**
166```powershell
167# Set the container registry endpoint
168azd env set AZURE_CONTAINER_REGISTRY_ENDPOINT (az acr list --resource-group <resource-group-name> --query "[0].loginServer" -o tsv)
169 
170# Set the managed identity resource ID
171azd env set AZURE_CONTAINER_REGISTRY_MANAGED_IDENTITY_ID (az identity list --resource-group <resource-group-name> --query "[0].id" -o tsv)
172 
173# Set the managed identity client ID
174azd env set MANAGED_IDENTITY_CLIENT_ID (az identity list --resource-group <resource-group-name> --query "[0].clientId" -o tsv)
175```
176 
177Then retry deployment:
178```bash
179azd deploy --no-prompt
180```
181 
182## Container Apps — RBAC Propagation Timeout
183 
184**Symptom:** During `azd up`, infrastructure provisions successfully but the Container App revision creation times out (~900s). Container App shows `provisioningState: Failed` with no active revision.
185 
186**Cause:** The managed identity's `AcrPull` role assignment hasn't propagated before the Container App attempts to pull the image from ACR. Azure RBAC propagation can take 1–5 minutes.
187 
188**Solution:**
189 
1901. Verify the `AcrPull` role exists on the ACR for the Container App's managed identity (see [AZD Errors — Container App Revision Timeout](recipes/azd/errors.md#container-app-revision-timeout))
1912. If missing, assign it manually with `--assignee-principal-type ServicePrincipal`
1923. Wait 2–5 minutes for RBAC propagation before retrying
1934. Set `AZURE_CONTAINER_REGISTRY_ENDPOINT` env var
1945. Run `azd deploy --no-prompt`; if it still fails, wait a little longer and retry with backoff until propagation completes
195 
196**Prevention:**
197 
198- Include `AcrPull` role assignment in Bicep with `principalType: 'ServicePrincipal'`
199- Use `azd provision` + `azd deploy` (separate steps) instead of `azd up` to allow propagation time
200