--- cuppy_hub: azure cuppy_path: reference/arm/deployment-errors.md cuppy_section: docs cuppy_doc: XADB-BPH0 cuppy_doc_uuid: cdacf46f-1e32-4df2-950f-37d377831fc4 cuppy_permalink: https://cuppy.io/azure/d/XADB-BPH0 cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/azure/docs/reference/arm/deployment-errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 29436d0ae9eb59b03b804361750290240b2bace8e43d0f977f2ba518b0de6670 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # ARM and Bicep deployment errors — template, dependency and state **`DeploymentFailed` is never the answer; it wraps the failing operation's own code.** Get that code first (`guides/arm/debug-failed-deployment.md`), then look it up here or in `reference/arm/errors.md` (subscription, quota, SKU, region). **Where the error appears tells you its type:** - **Compile:** `bicep build` prints `BCP…` codes with line and column (`reference/bicep/compile-errors.md`). - **Validation and preflight:** the command fails before anything deploys, often as `InvalidTemplateDeployment` wrapping the real reason. These errors appear in the Activity log, **not** in deployment history. - **Deployment:** a resource operation failed. These appear in deployment history and in `az deployment operation group list`. ## Template and validation | Error | Cause → fix | Check | |---|---|---| | `InvalidTemplate` `Deployment template validation failed` | A syntax or expression error, an invalid parameter value, or a circular dependency. The message varies with the cause | `bicep build main.bicep`; `az deployment group validate -g --template-file main.bicep` | | `InvalidTemplate` about type and name segments (`MismatchingResourceSegments`) | The name has a different number of `/` segments than the type: `Microsoft.KeyVault/vaults/secrets` needs `vault/secret`. In Bicep, use `parent:` and give the child a one-segment name | Count segments in `type` and `name` | | `InvalidTemplateDeployment` | Preflight rejected a resource: the inner message holds the real reason (SKU not available, a policy, a quota) | The inner `message` | | `InvalidParameter`, `InvalidRequestContent` | A value the provider refuses (weak password, bad name) or an unknown or missing property. The message names it | The resource's API reference for that API version | | `PasswordTooLong` | Often a password converted to a secure string before being passed to a `@secure()` parameter: pass the plain value | — | | `InvalidContentLink` | A linked template URI that isn't reachable (private storage without a SAS) | `curl -I ` | | `DeploymentNameInvalidCharacters` / `DeploymentNameLengthLimitExceeded` | Deployment names: letters, digits, `-`, `.`, `_`; at most 64 characters | The `--name` you passed | | `InvalidDeploymentLocation` | A subscription-scope deployment name was reused with a different `--location`. Use a new name or the same location | `az deployment sub show --name --query location` | | `DeploymentJobSizeExceeded` / `JobSizeExceeded` | The deployment job is over **1 MB** compressed (template plus metadata), the template over **4 MB**, or one resource over **1 MB**, after loops expand. Remove unneeded `dependsOn` (loop-to-loop dependencies grow as n²), move large data out, split into modules | `bicep build` output size | ## Dependencies and references | Error | Cause → fix | Check | |---|---|---| | `NotFound` `Cannot find ServerFarm with name .` | Parent and dependent were deployed in parallel because nothing linked them. In Bicep, reference the other resource by **symbolic name** (`serverFarmId: plan.id`) to create the dependency; `resourceId()` strings create none | Does the dependent use the symbol or a string ID? | | `ResourceNotFound` `The Resource '/' under resource group was not found.` | `existing` or `reference()` points at something missing, in another group or subscription without `scope:`, or not created yet | `az resource show --ids ` | | `ParentResourceNotFound` `Can not perform requested operation on nested resource. Parent resource '' not found.` | The child started before its parent, or names a parent that doesn't exist. Use `parent: ` | `az resource show` on the parent | | `InvalidTemplateCircularDependency`, `TemplateResourceCircularDependency` | Two resources depend on each other. Remove explicit `dependsOn` you don't need: Bicep infers them | `bicep build` warnings `no-unnecessary-dependson` | | `InvalidResourceReference`, `LinkedInvalidPropertyId` | A resource ID that didn't resolve: a missing subscription, group, parent or name segment | Print the ID expression's value as an output | ## State and concurrency | Error | Cause → fix | Check | |---|---|---| | `DeploymentActiveAndUneditable` | Another deployment with that name is running in the group. Wait, or use a unique name | `az deployment group list -g --query "[?properties.provisioningState=='Running'].name"` | | `AnotherOperationInProgress`; `The specified precondition 'If-Match = …' failed.` | Two operations on the same resource at once (two pipelines, a portal edit, or missing dependencies in one template). Serialize; retry | The Activity log for the resource | | `Conflict` | The operation isn't allowed in the resource's current state (for example, resizing a disk on a running VM) | The resource's `provisioningState` and power state | | `PropertyChangeNotAllowed` | The property can't be changed on a deployed resource. Change only permitted properties, or create a new resource | The provider's API reference for that property | | `InUseSubnetCannotBeDeleted` | An update that deletes and re-creates part of a resource, typically a VNet redeployed **without** its subnets: incremental mode reapplies every property, so omitted values are removed (the hub's reading of the two Microsoft pages). Declare subnets in the VNet's `subnets` property, not as separate child resources, and specify all unchanged values | Compare the template's subnets with `az network vnet subnet list` | | `DeploymentQuotaExceeded` | 800 deployments per resource group. Resource Manager auto-deletes near the limit unless a `CanNotDelete` lock blocks it, you opted out, or many run at once. `az deployment group delete -g -n ` | `az deployment group list -g --query "length(@)"` | | `DeploymentFailedCleanUp` | Complete mode couldn't delete resources missing from the template (no permission). Microsoft is deprecating complete mode: use deployment stacks for deletions | `reference/arm/deployment-stacks.md` | ## When none of these fits Re-run with `--debug`, or set the deployment's `debugSetting.detailLevel` to `requestContent,responseContent`. That logs the request and response of each operation, secrets included, so use it once and then turn it off. Then read the failing operation's `statusMessage` in full. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 107 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/azure/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.