Edit

Share via

Quickstart: Troubleshoot Bicep file deployments

  • Article

This quickstart describes how to troubleshoot Bicep file deployment errors. You'll create a file with errors and learn how to fix the 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.

Prerequisites

To complete this quickstart, you need the following items:

Create a Bicep file with errors

Copy the following Bicep file 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.bicep but you can give it any name.

Bicep 
@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
  name: 'doesnotexist'
}

output storageAccountName string = storageAccountName
output vnetResult object = existingVNet

Fix validation error

Open the file in Visual Studio Code. You'll notice that Visual Studio Code identifies a syntax error. The first parameter declaration is marked with red squiggles to indicate an error.

Screenshot of Visual Studio Code with red squiggles highlighting a syntax error in a Bicep file.

The lines marked with an error are:

Bicep 
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

When you hover over parameter, you see an error message.

Screenshot of a detailed error message displayed in Visual Studio Code when hovering over a syntax error in a Bicep file.

The message states: This declaration type is not recognized. Specify a parameter, variable, resource, or output declaration. If you attempt to deploy this file, you'll get the same error message from the deployment command.

If you look at the documentation for a parameter declaration, you'll see the keyword is actually param. When you change that syntax, the validation error disappears. The @allowed decorator was also marked as an error, but that error is also resolved by changing the parameter declaration. The decorator was marked as an error because it expects a parameter declaration after the decorator. This condition wasn't true when the declaration was incorrect.

The fixed line is:

Bicep 
param storageAccountType string = 'Standard_LRS'

Fix preflight error

Now that you've fixed the validation error, it's time to deploy the file. But, you'll provide a bad parameter value to see a preflight error.

Azure CLI 
az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

Azure Resource Manager determines that the name of the storage account contains characters that aren't allowed. It doesn't attempt the deployment.

You see an error message that indicates preflight validation failed. You also get a message that says the storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only. The prefix you provided didn't meet that requirement. For more information about this error code, see Resolve errors for storage account names.

Because the error was caught in preflight, no deployment exists in the history.

Screenshot of Azure portal's deployment history section showing no deployments for a Bicep file.

But, the failed deployment exists in the Activity Log.

Screenshot of Azure portal's activity log displaying a preflight validation error for a Bicep file deployment.

You can open details of the log entry to see the error message.

Fix deployment error

You'll deploy the file again and provide an allowed value for the name prefix parameter.

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

The deployment starts but fails with a message that the virtual network wasn't found. Typically, you would fix this error by changing the reference to the resource. In this quickstart, you'll delete the reference. For more information about this error code, see Resolve resource not found errors.

Notice in the portal that the deployment appears in the history.

Screenshot of Azure portal's deployment history section showing a failed deployment for a Bicep file.

You can open the entry in the deployment history to get details about the error. The error also exists in the activity log.

The Bicep file attempts to reference a virtual network that doesn't exist in your resource group. Delete the reference to the existing virtual network to fix the error.

Bicep 
@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

output storageAccountName string = storageAccountName

You can deploy that Bicep file without any errors.

Clean up resources

When the Azure resources are no longer needed, delete the resource group. You can delete the resource group from Cloud Shell or the portal.

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 Bicep file deployment errors.

Troubleshoot common Azure deployment errors