| title | description | tags | ms.topic | ms.custom | ms.date |
|---|---|---|---|---|---|
Find error codes |
Describes how to find error codes to troubleshoot Azure resources deployed with Azure Resource Manager templates (ARM templates) or Bicep files. |
top-support-issue |
troubleshooting |
devx-track-azurepowershell, devx-track-arm-template, devx-track-bicep, devx-track-azurecli |
06/20/2024 |
When an Azure resource deployment fails using Azure Resource Manager templates (ARM templates) or Bicep files, an error code is received. This article describes how to find error codes so you can troubleshoot the problem. For more information about error codes, see common deployment errors.
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. A Bicep file with syntax errors doesn't compile into JSON and isn't shown in the activity log.
To identify syntax errors, you can use Visual Studio Code with the latest Bicep extension or Azure Resource Manager Tools extension.
Templates are validated during the deployment process and error codes are displayed. Before you run a deployment, you can identify validation and preflight errors by running validation tests with Azure PowerShell or Azure CLI.
An ARM template can be deployed from the portal. If the template has syntax errors, you'll see a validation error when you try to run the deployment. For more information about portal deployments, see deploy resources from custom template.
The following example attempts to deploy a storage account and a validation error occurs.
:::image type="content" source="media/find-error-code/validation-error.png" alt-text="Screenshot of a validation error in the Azure portal for a storage account deployment attempt.":::
Select the message for more details. The template has a syntax error with error code InvalidTemplate. The Summary shows an expression is missing a closing parenthesis.
:::image type="content" source="media/find-error-code/validation-details.png" alt-text="Screenshot of a validation error message in the Azure portal, showing a syntax error with error code InvalidTemplate.":::
To validate an ARM template before deployment run Test-AzResourceGroupDeployment.
Test-AzResourceGroupDeployment `
-ResourceGroupName examplegroup `
-TemplateFile azuredeploy.json
The output displays error codes like InvalidTemplateDeployment or AccountNameInvalid that you can use to troubleshoot and fix the template.
For a Bicep file, the output for a syntax validation problem shows a parameter error.
Test-AzResourceGroupDeployment: Cannot retrieve the dynamic parameters for the cmdlet.
Cannot find path '/tmp/11111111-1111-1111-1111-111111111111/main.json' because it does not exist.
To get more troubleshooting information, use the Bicep build command. The output shows each error's line and column number in parentheses, and the error message.
bicep build main.bicep/azuredeploy.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
/azuredeploy.bicep(22,51) : Error BCP004: The string at this location is not terminated due to an
unexpected new line character.
There are Azure PowerShell cmdlets to validate deployment templates for the subscription, management group, and tenant scopes.
| Scope | Cmdlets |
|---|---|
| Subscription | Test-AzDeployment |
| Management group | Test-AzManagementGroupDeployment |
| Tenant | Test-AzTenantDeployment |
To validate an ARM template before deployment, run az deployment group validate.
az deployment group validate \
--resource-group examplegroup \
--template-file azuredeploy.json
The output displays error codes like InvalidTemplateDeployment or AccountNameInvalid that you can use to troubleshoot and fix the template.
For a Bicep file, the output shows each error's line and column number in parentheses, and the error message.
az deployment group validate \
--resource-group examplegroup \
--template-file main.bicep
/azuredeploy.bicep(22,51) : Error BCP064: Found unexpected tokens in interpolated expression.
/azuredeploy.bicep(22,51) : Error BCP004: The string at this location is not terminated due to an
unexpected new line character.
There are Azure CLI commands to validate deployment templates for the subscription, management group, and tenant scopes.
| Scope | Commands |
|---|---|
| Subscription | az deployment sub validate |
| Management group | az deployment mg validate |
| Tenant | az deployment tenant validate |
Several operations are processed to deploy an Azure resource. Deployment errors occur when an operation passes validation but fails during deployment. You can view messages about each deployment operation and each deployment for a resource group.
To see messages about a deployment's operations, use the resource group's Activity log:
-
Sign in to Azure portal.
-
Go to Resource groups and select the deployment's resource group name.
-
Select Activity log.
-
Use the filters to find an operation's error log.
:::image type="content" source="./media/find-error-code/activity-log.png" alt-text="Screenshot of the Azure portal's resource group activity log, emphasizing a failed deployment with an error log.":::
-
Select the error log to see the operation's details.
:::image type="content" source="./media/find-error-code/activity-log-details.png" alt-text="Screenshot of the activity log details in the Azure portal, showing a failed deployment's error message and operation details.":::
To view a deployment's result:
-
Go to the resource group.
-
Select Settings > Deployments.
-
Select Error details for the deployment.
:::image type="content" source="media/find-error-code/deployment-error-details.png" alt-text="Screenshot of a resource group's deployments section in the Azure portal, displaying a link to error details for a failed deployment.":::
-
The error message and error code
NoRegisteredProviderFoundare shown.:::image type="content" source="media/find-error-code/deployment-error-summary.png" alt-text="Screenshot of a deployment error summary in the Azure portal, showing the error message and error code NoRegisteredProviderFound.":::
To see a deployment's operations messages with PowerShell, use Get-AzResourceGroupDeploymentOperation.
To show all the operations for a deployment:
Get-AzResourceGroupDeploymentOperation `
-DeploymentName exampledeployment `
-ResourceGroupName examplegroup
To specify a specific property type:
(Get-AzResourceGroupDeploymentOperation `
-DeploymentName exampledeployment `
-ResourceGroupName examplegroup).StatusCode
To get a deployment's result, use Get-AzResourceGroupDeployment.
Get-AzResourceGroupDeployment `
-DeploymentName exampledeployment `
-ResourceGroupName examplegroup
There are Azure PowerShell cmdlets to get deployment information for the subscription, management group, and tenant scopes.
| Scope | Cmdlets |
|---|---|
| Subscription | Get-AzDeploymentOperation Get-AzDeployment |
| Management group | Get-AzManagementGroupDeploymentOperation Get-AzManagementGroupDeployment |
| Tenant | Get-AzTenantDeploymentOperation Get-AzTenantDeployment |
To see a deployment's operations messages with Azure CLI, use az deployment operation group list.
To show all the operations for a deployment:
az deployment operation group list \
--name exampledeployment \
--resource-group examplegroup \
--query "[*].properties"
To specify a specific property type:
az deployment operation group list \
--name exampledeployment \
--resource-group examplegroup \
--query "[*].properties.statusCode"
To get a deployment's result, use az deployment group show.
az deployment group show \
--resource-group examplegroup \
--name exampledeployment
There are Azure CLI commands to get deployment information for the subscription, management group, and tenant scopes.
| Scope | Commands |
|---|---|
| Subscription | az deployment operation sub list az deployment sub show |
| Management group | az deployment operation mg list az deployment mg show |
| Tenant | az deployment operation tenant list az deployment tenant show |