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 <rg> --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 <uri>`
`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 <n> --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 <plan>.`	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 '<type>/<name>' under resource group <rg> 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 <id>`
`ParentResourceNotFound` `Can not perform requested operation on nested resource. Parent resource '<name>' not found.`	The child started before its parent, or names a parent that doesn't exist. Use `parent: <symbol>`	`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 <rg> --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 <rg> -n <old>`	`az deployment group list -g <rg> --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.