Quickstart: Troubleshoot ARM template JSON deployments
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:
- If you don't have an Azure subscription, create a trial subscription before you begin.
- Visual Studio Code with the latest Azure Resource Manager Tools extension.
- Install the latest version of Azure PowerShell or Azure CLI.
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.
{
"$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.
You'll notice that variables and resources have errors for undefined parameter reference. To display the template's validation errors, select View > Problems.
All the errors are caused by the incorrect spelling of an element name.
"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.
"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.
az group create --name troubleshootRG --location chinanorth
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.
The activity log shows the preflight error. Select the log to see the error's details.
Fix deployment error
Run the deployment with a valid prefix value, like storage.
az group create --name troubleshootRG --location chinanorth
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.
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.
"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.
{
"$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.
az group delete --name troubleshootRG
To delete the resource group from the portal, follow these steps:
- In the Azure portal, enter Resource groups in the search box.
- In the Filter by name field, enter the resource group name.
- Select the resource group name.
- Select Delete resource group.
- 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.