Edit

Share via

Quickstart: Troubleshoot ARM template JSON deployments

  • Article

This quickstart describes how to troubleshoot Azure Resource Manager template (ARM template) JSON deployment errors. You'll set up a template with errors and learn how to fix the errors.

An Azure Resource Manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. You describe your intended deployment without writing the sequence of programming commands to create the deployment.

There are three types of errors that are related to a deployment:

  • Validation errors occur before a deployment begins and are caused by syntax errors in your file. A code editor like Visual Studio Code can identify these errors.
  • Preflight validation errors occur when a deployment command is run but resources aren't deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in preflight validation.
  • Deployment errors occur during the deployment process and can only be found by assessing the deployment's progress in your Azure environment.

All types of errors return an error code that you use to troubleshoot the deployment. Validation and preflight errors are shown in the activity log but don't appear in your deployment history.

Prerequisites

To complete this quickstart, you need the following items:

Create a template with errors

Copy the following template and save it locally. You'll use this file to troubleshoot a validation error, a preflight error, and a deployment error. This quickstart assumes you've named the file troubleshoot.json but you can use any name.

JSON 
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameterss": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    },
    "vnetResult": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
    }
  }
}

Fix validation error

Open the file in Visual Studio Code. The wavy line under parameterss: indicates an error. To see the validation error, hover over the error.

Screenshot of Visual Studio Code highlighting a template validation error with a red wavy line under the misspelled 'parameterss:' in the code.

You'll notice that variables and resources have errors for undefined parameter reference. To display the template's validation errors, select View > Problems.

Screenshot of Visual Studio Code showing the Problems tab listing undefined parameter reference errors for 'variables' and 'resources' sections.

All the errors are caused by the incorrect spelling of an element name.

JSON 
"parameterss": {

The error message states Template validation failed: Could not find member 'parameterss' on object of type 'Template'. Path 'parameterss', line 4, position 16.

The ARM template syntax for parameters shows that parameters is the correct element name.

To fix the validation error and undefined parameter reference errors, correct the spelling and save the file.

JSON 
"parameters": {

Fix preflight error

To create a preflight validation error, you'll use an incorrect value for the prefixName parameter.

This quickstart uses troubleshootRG for the resource group name, but you can use any name.

Azure CLI 
az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=long!!StoragePrefix

The template fails preflight validation and the deployment isn't run. The prefixName is more than 11 characters and contains special characters and uppercase letters.

Storage names must be between 3 and 24 characters and use only lowercase letters and numbers. The prefix value created an invalid storage name. For more information, see Resolve errors for storage account names. To fix the preflight error, use a prefix that's 11 characters or less and contains only lowercase letters or numbers.

Because the deployment didn't run, there's no deployment history.

Screenshot of Azure resource group overview page displaying an empty deployment history section due to a preflight error.

The activity log shows the preflight error. Select the log to see the error's details.

Screenshot of Azure resource group activity log showing a preflight error entry with a red exclamation mark icon.

Fix deployment error

Run the deployment with a valid prefix value, like storage.

Azure CLI 
az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=storage

The deployment begins and is visible in the deployment history. The deployment fails because outputs references a virtual network that doesn't exist in the resource group. However, there were no errors for the storage account, so the resource deployed. The deployment history shows a failed deployment.

Screenshot of Azure resource group overview page showing a failed deployment with a red exclamation mark icon in the deployment history section.

To fix the deployment error, change the reference function to use a valid resource. For more information, see Resolve resource not found errors. For this quickstart, delete the comma that precedes vnetResult and all of vnetResult. Save the file and rerun the deployment.

JSON 
"vnetResult": {
  "type": "object",
  "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
}

After the validation, preflight, and deployment errors are fixed, the following template deploys a storage account. The deployment history and activity log show a successful deployment.

JSON 
{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

Clean up resources

When the Azure resources are no longer needed, delete the resource group.

Azure CLI 
az group delete --name troubleshootRG

To delete the resource group from the portal, follow these steps:

  1. In the Azure portal, enter Resource groups in the search box.
  2. In the Filter by name field, enter the resource group name.
  3. Select the resource group name.
  4. Select Delete resource group.
  5. To confirm the deletion, enter the resource group name and select Delete.

Next steps

In this quickstart, you learned how to troubleshoot ARM template deployment errors.

Troubleshoot common Azure deployment errors