How to Fix Azure Resource Manager Templates

The very first line of every ARM template is the $schema declaration. This is not decoration, Azure Resource Manager uses it to determine what deployment scope you're targeting and which validation rules apply. If you copy a template and don't update this line, you'll get confusing errors that seem unrelated to the actual problem.

Here's the mapping you need to know:

# Resource Group scope (most common)
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"

# Subscription scope
"$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#"

# Management Group scope
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#"

# Tenant scope
"$schema": "https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#"

Open your azuredeploy.json file and check this first. Then check that your contentVersion follows the 1.0.0.0 format, it's a required field and must be a string in that format.

Next, validate the overall JSON structure. Your ARM template must have these top-level keys in valid JSON: $schema, contentVersion, and resources. The parameters, variables, functions, and outputs keys are optional but must be properly formed if present.

The fastest way to check raw JSON validity is to paste your template into Visual Studio Code with the Prettier extension installed, then run Format Document (Shift+Alt+F on Windows). If your JSON has syntax errors, VS Code will flag them with red underlines before you even touch Azure. After confirming the JSON is structurally valid, run the az deployment group validate command from the Quick Fix section. If validation passes, move on. If not, the error output will now make a lot more sense.

This is the single most common Azure Resource Manager template error I see. Every resource block in your template requires an apiVersion field, and it must be a version that actually exists for that specific resource type. Use a made-up version, a typo, or a version that was retired, and you'll get a validation error like: "No registered resource provider found for location X and API version Y for type Z."

Here's an example of a correctly structured storage account resource with a valid API version:

{
  "type": "Microsoft.Storage/storageAccounts",
  "apiVersion": "2025-06-01",
  "name": "mystorageaccount",
  "location": "[parameters('location')]",
  "sku": {
    "name": "Standard_LRS"
  },
  "kind": "StorageV2"
}

To find valid API versions for any resource type, run this Azure CLI command:

az provider show \
  --namespace Microsoft.Storage \
  --query "resourceTypes[?resourceType=='storageAccounts'].apiVersions[]" \
  --output table

Replace Microsoft.Storage with your resource provider namespace and storageAccounts with your resource type. This returns every supported API version, including preview versions. Pick the most recent stable (non-preview) version unless you specifically need a preview feature.

One thing the official docs make very clear: once you choose an API version and your template is deployed and working, stick with it. The idempotent nature of ARM templates means you can redeploy the same template repeatedly and get consistent results, but only if the API version stays constant. Bumping the API version in a running template can introduce breaking changes from the newer API contract that cause previously working deployments to fail.

After fixing API versions, rerun validation. If it clears, proceed to step 3.

ARM template expressions use a function-based syntax inside square brackets: [expression]. When these expressions reference parameters, variables, or resource outputs incorrectly, deployment fails with errors like "Template parameter 'location' is not found" or "The template function 'reference' is not expected here."

The most common parameter mistakes:

// WRONG - typo in parameter name
"location": "[parameters('locaton')]"

// WRONG - referencing a parameter that isn't declared
"location": "[parameters('region')]"

// CORRECT - parameter declared AND referenced consistently
"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
},
...
"location": "[parameters('location')]"

Go through your template and do a manual audit: every parameters('X') call must have a matching X key in the top-level parameters block. Same rule applies to variables('X'), every variable reference must have a corresponding entry in variables.

Watch for type mismatches too. If a parameter is declared as "type": "int" but you're passing it a quoted string value in your parameters file, ARM will reject it. Your parameters file must pass values in the correct JSON type, integers without quotes, booleans as true/false without quotes, strings with quotes.

For parameters with allowedValues restrictions, the value in your parameters file must exactly match one of the allowed values, case-sensitive. Check this carefully if you're getting parameter validation errors that seem inexplicable.

Once you've verified every parameter and variable reference is consistent, run az deployment group validate again. Expression errors are among the most reliably caught by the validator.

One of ARM's most powerful features is that it deploys resources in parallel wherever possible. Resource Manager figures out the dependency graph and spins up independent resources simultaneously, which is why ARM deployments finish much faster than running a sequence of imperative CLI commands. But when you haven't told ARM about a dependency, it may try to deploy a resource before its prerequisite exists, and that's when you see errors like "Resource not found" or "The referenced resource does not exist" mid-deployment.

Use the dependsOn property to declare explicit dependencies:

{
  "type": "Microsoft.Network/networkInterfaces",
  "apiVersion": "2024-01-01",
  "name": "myNetworkInterface",
  "dependsOn": [
    "[resourceId('Microsoft.Network/virtualNetworks', 'myVNet')]",
    "[resourceId('Microsoft.Network/publicIPAddresses', 'myPublicIP')]"
  ],
  ...
}

The resourceId() function inside dependsOn is the correct pattern. Do not use the resource name as a plain string, use resourceId() so ARM can resolve the dependency correctly even across scopes.

A few rules to keep in mind:

• Only declare direct dependencies in dependsOn. If Resource C depends on Resource B which depends on Resource A, you only need to declare C → B and B → A. Don't add C → A as well, ARM already infers transitive dependencies.
• Circular dependencies will cause an immediate deployment failure. If Resource A depends on Resource B and Resource B depends on Resource A, the template is invalid. Refactor your resources to break the cycle.
• For child resources defined inline inside a parent resource, the dependency is implicit, you don't need dependsOn.

After adding or correcting dependsOn declarations, run a what-if deployment. The output will show the planned creation order, which lets you visually verify the dependency chain looks right before committing to a real deployment.

When your ARM template deployment fails mid-flight, meaning validation passed and the deployment started but then stopped with an error, you need to dig into the deployment history to find out exactly which resource failed and why.

In the Azure Portal: navigate to your Resource Group, then select Settings > Deployments from the left menu. You'll see a list of all deployments for that resource group with status indicators. Click the failed deployment name, then look at the Operations tab. This shows every individual resource operation with its own status. Click any failed operation to see the full error detail, including the error code and message from the resource provider.

The error code is the key piece. Some common ones you'll encounter:

InvalidTemplate         , template structure or expression error
ResourceNotFound        , a referenced resource doesn't exist yet (dependency issue)
RequestDisallowedByPolicy, Azure Policy is blocking the resource type or config
QuotaExceeded           , subscription regional quota reached
AuthorizationFailed     , RBAC permissions insufficient for the deploying identity
InvalidResourceType     , resource type doesn't exist in the target region
Conflict                , resource already exists with different properties

From the CLI, you can pull deployment operation details directly:

az deployment operation group list \
  --resource-group YOUR-RESOURCE-GROUP \
  --name YOUR-DEPLOYMENT-NAME \
  --query "[?properties.provisioningState=='Failed']" \
  --output json

The JSON output gives you the statusMessage field with the full error detail from the resource provider, often more verbose than what the portal shows. Once you identify the specific resource and error code, you have a precise fix target. Address it, rerun the template, and monitor the Operations tab again to confirm that resource now succeeds.