Azure Developer CLI (azd) errors

azd provision is a Bicep deployment, so most of its failures are ARM errors with azd's wording around them. The real error is in the resource group azd created (rg-<environment-name> in most templates) under Deployments, or through guides/arm/debug-failed-deployment.md. Re-run with --debug for azd's own trace, and redact it before sharing.

azd's state: each environment is a folder under .azure/ in the project (its .env holds AZURE_ENV_NAME, AZURE_LOCATION, AZURE_SUBSCRIPTION_ID and outputs). azd treats every folder in .azure as an environment, so don't run azd from your home directory, where the Azure CLI keeps its own .azure.

Errors

Message	Cause → fix	Check
`… Authorization failed for template resource '<guid>' of type 'Microsoft.Authorization/roleAssignments'. The client '<you>' with object id '<id>' does not have permission to perform action 'Microsoft.Authorization/roleAssignments/write' …`	The template assigns roles (most azd templates do, for managed identities) and you have only Contributor. You need Owner, User Access Administrator or Role Based Access Control Administrator on the target scope; otherwise someone with it runs the first deployment	`az role assignment list --assignee <your-object-id> --all --include-inherited -o table`
`The role assignment already exists.`	Often intermittent: retry `azd up`. Templates should name role assignments with `guid()`	`reference/rbac/errors.md`
`Tenant ID, application ID, principal ID, and scope are not allowed to be updated.`	The same role-assignment resource is now targeting a different principal (for example, switching between your user and a service principal). Delete the old assignment, or keep the principal stable	`az role assignment list --scope <scope> -o table`
`The region '<r>' currently does not have enough resources available to provision services with the SKU '<sku>'.`	Capacity, common for AI services in busy regions. `azd env set AZURE_LOCATION <region>` and provision again	`az account list-locations -o table`
`This operation require <n> new capacity in quota Tokens Per Minute (thousands) - <model> - GlobalStandard, which is bigger than the current available capacity <n>.`	Azure OpenAI model quota in that region (Azure OpenAI family)	Quota in the Foundry portal
`The specified precondition 'If-Match = "<guid>"' failed.`	A concurrent update: another pipeline or person deploying the same environment, or resources the template updates in parallel. Retry; serialize deployments	Recent deployments in `rg-<env>`
`Call to Microsoft.CognitiveServices/accounts failed. Error message: Account <id> in state Accepted.`	A dependent resource touched the account before it finished provisioning. Retry, or add a `postprovision` hook that waits	The account's `provisioningState`
`ERROR: resolving '<name>': AZURE_RESOURCE_<NAME>_ID is not set as an output variable` (`azd show`)	The resource isn't in `azure.yaml` under `resources:`, or isn't provisioned, or the template doesn't output its ID	The template's outputs; `azd env get-values`
New role or subscription not seen by azd	azd caches credentials and permissions: `azd auth logout`, then `azd auth login`	—
Bicep build errors from azd	azd installs its own Bicep; set `AZD_BICEP_TOOL_PATH` to use a specific build	`bicep --version`
Region out of capacity / provider not present there	ARM capacity or provider errors	`reference/arm/errors.md`

When none of these fits

Open the failed deployment in rg-<env> and read its operations; the ARM catalogues (reference/arm/deployment-errors.md, reference/arm/errors.md) take it from there.