You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to monitor and troubleshoot Bicep file deployments. Shows activity logs and deployment history.
4
-
ms.date: 11/01/2021
4
+
ms.date: 10/26/2021
5
5
ms.topic: quickstart
6
6
ms.custom: devx-track-azurepowershell
7
7
---
8
8
9
9
# Quickstart: Troubleshoot Bicep file deployments
10
10
11
-
This quickstart describes how to troubleshoot Bicep file deployment errors. You'll set up a file with two errors and learn how to use the activity logs and deployment history to fix the errors.
11
+
This quickstart describes how to troubleshoot Bicep file deployment errors. You'll create a file with errors and learn how to fix the errors.
12
12
13
-
There are two types of errors that are related to a deployment:
13
+
There are three types of errors that are related to a deployment:
14
14
15
-
-**Validation errors** occur before a deployment begins and are caused by syntax errors in your file.
16
-
-**Deployment errors** occur during the deployment process and can be caused by an incorrect value, such as an API version.
15
+
-**Validation errors** occur before a deployment begins and are caused by syntax errors in your file. Your editor can catch these errors.
16
+
-**Preflight errors** occur after you've started the deployment, but before any resources have been deployed. These errors are found without starting the deployment. For example, if a parameter value is incorrect, the error is found in preflight validation.
17
+
-**Deployment errors** occur during the deployment process and can only be found by assessing the deployment's progress.
17
18
18
-
Both types of errors return an error code that you use to troubleshoot the deployment. Bicep file validation errors don't appear in your activity log or deployment history.
19
+
All types of errors return an error code that you use to troubleshoot the deployment. Validation and preflight errors don't appear in your deployment history.
19
20
20
21
## Prerequisites
21
22
22
23
To complete this quickstart, you need the following items:
23
24
24
25
- If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
25
26
-[Visual Studio Code](https://code.visualstudio.com) with the latest [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep).
26
-
-Review how to deploy a local Bicep file with [Azure Cloud Shell](../bicep/deploy-cloud-shell.md).
27
+
-The latest version of either [Azure PowerShell](/powershell/azure/install-az-ps) or [Azure CLI](/cli/azure/install-azure-cli).
27
28
28
29
## Create a Bicep file with errors
29
30
30
-
The following Bicep file contains a validation error and a deployment error. You'll troubleshoot and fix the file's errors so the storage account can be deployed.
31
-
32
-
The sample file's errors are on the following two lines:
31
+
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.
Upload the Bicep file to Cloud Shell and deploy with Azure CLI or Azure PowerShell.
68
+
Open the file in Visual Studio Code. You'll notice that VS Code identifies a syntax error. The first parameter declaration is marked with red squiggles to indicate an error.
75
69
76
-
1. Sign in to [Cloud Shell](https://shell.azure.com).
77
-
1. Select **Bash** or **PowerShell** from the upper left corner.
70
+
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/show-vs-code-error.png" alt-text="Screenshot of VS Code showing error in syntax.":::
78
71
79
-
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/cloud-shell-upload.png" alt-text="Screenshot of Azure Cloud Shell to select a shell and upload a file.":::
72
+
The lines marked with an error are:
80
73
81
-
1. Select **Upload/Download files** and upload your _azuredeploy.bicep_ file.
82
-
1. To deploy the Bicep file, copy and paste the following commands into the shell window.
When you hover over `parameter`, you see an error message.
85
85
86
-
```azurecli
87
-
echo "Enter a resource group name:" &&
88
-
read resourceGroupName &&
89
-
echo "Enter the location (i.e. centralus):" &&
90
-
read location &&
91
-
az group create --name $resourceGroupName --location $location &&
92
-
az deployment group create --resource-group $resourceGroupName --template-file $HOME/azuredeploy.bicep &&
93
-
echo "Press [ENTER] to continue ..."
94
-
```
86
+
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/declaration-not-recognized.png" alt-text="Screenshot of error message in VS Code.":::
95
87
96
-
# [PowerShell](#tab/azure-powershell)
88
+
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.
97
89
98
-
```azurepowershell
99
-
$resourceGroupName = Read-Host -Prompt "Enter a resource group name"
100
-
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
If you look at the documentation for a [parameter declaration](../bicep/parameters.md), 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.
105
91
106
-
---
92
+
The fixed line is:
107
93
108
-
> [!NOTE]
109
-
> Use the same resource group name and location as you run the deployments. When you're prompted to update the resource group select **Yes**.
94
+
```bicep
95
+
param storageAccountType string = 'Standard_LRS'
96
+
```
110
97
111
-
## Troubleshoot the validation error
98
+
## Fix preflight error
112
99
113
-
The validation error displays an error message in the shell because there's a parameter declaration problem. An error can cause other errors to appear for dependent resources.
100
+
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.
114
101
115
102
# [Azure CLI](#tab/azure-cli)
116
103
117
-
The [Bicep linter](../bicep/linter.md) is built into Bicep CLI version 0.4 or later, and integrates with Cloud Shell to display error messages. The line and column number, such as `(8,1)`, shows where an error is located in a Bicep file.
118
-
119
-
```Output
120
-
/azuredeploy.bicep(2,1) : Error BCP147: Expected a parameter declaration after the decorator.
121
-
/azuredeploy.bicep(8,1) : Error BCP007: This declaration type is not recognized.
122
-
Specify a parameter, variable, resource, or output declaration.
123
-
/azuredeploy.bicep(15,25) : Warning BCP081: Resource type "Microsoft.Storage/storageAccounts@2018-07-02"
124
-
does not have types available.
125
-
/azuredeploy.bicep(19,11) : Error BCP082: The name "storageAccountType" does not exist in the current context.
126
-
Did you mean "storageAccountName"?
104
+
```azurecli
105
+
az group create --name troubleshootRG --location westus
106
+
az deployment group create --resource-group troubleshootRG --template-file troubleshoot.bicep --parameters prefixName=longNamewith##Charactersthatarenotallowed
127
107
```
128
108
129
109
# [PowerShell](#tab/azure-powershell)
130
110
131
-
The PowerShell output shows a generic parameter error.
132
-
133
-
```Output
134
-
New-AzResourceGroupDeployment: Cannot retrieve the dynamic parameters for the cmdlet.
135
-
Cannot find path '/tmp/11111111-1111-1111-1111-111111111111/azuredeploy.json' because it does not exist.
To get more information, use the `build` command to run the [Bicep linter](../bicep/linter.md). The line and column number, such as `(8,1)`, shows where an error is located in a Bicep file.
116
+
---
139
117
140
-
```bicep
141
-
bicep build ./azuredeploy.bicep
142
-
```
118
+
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.
143
119
144
-
```Output
145
-
/azuredeploy.bicep(2,1) : Error BCP147: Expected a parameter declaration after the decorator.
146
-
/azuredeploy.bicep(8,1) : Error BCP007: This declaration type is not recognized.
147
-
Specify a parameter, variable, resource, or output declaration.
148
-
/azuredeploy.bicep(15,25) : Warning BCP081: Resource type "Microsoft.Storage/storageAccounts@2018-07-02"
149
-
does not have types available.
150
-
/azuredeploy.bicep(19,11) : Error BCP082: The name "storageAccountType" does not exist in the current context.
151
-
Did you mean "storageAccountName"?
152
-
```
120
+
Because the error was caught in preflight, no deployment exists in the history.
153
121
154
-
---
122
+
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/no-deployment.png" alt-text="Screenshot of portal with no deployment in the history.":::
123
+
124
+
But, the failed deployment exists in the Activity Log.
155
125
156
-
### Fix the validation error
126
+
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/preflight-activity-log.png" alt-text="Screenshot of activity log with error.":::
157
127
158
-
The error message indicates a problem with the parameter declaration. Use Visual Studio Code to change `parameter` to `param`, and save the Bicep file. Follow the steps in [deploy the Bicep file](#deploy-the-bicep-file) to upload the file and rerun the deployment.
128
+
You can open details of the log entry to see the error message.
159
129
160
-
## Troubleshoot the deployment error
130
+
## Fix deployment error
161
131
162
-
The deployment error displays an error message in the shell with the error code `NoRegisteredProviderFound`. You can also view the errors in the resource group's **Deployments** and **Activity log**.
132
+
You'll deploy the file again and provide an allowed value for the name prefix parameter.
163
133
164
134
# [Azure CLI](#tab/azure-cli)
165
135
166
-
```Output
167
-
azuredeploy.bicep(15,25) : Warning BCP081: Resource type "Microsoft.Storage/storageAccounts@2018-07-02"
168
-
does not have types available.
169
-
170
-
{"status":"Failed","error":{"code":"DeploymentFailed","message":"At least one resource deployment operation
171
-
failed. Please list deployment operations for details. Please see https://aka.ms/DeployOperations for usage
The deployment error is shown in the Azure portal:
219
-
220
-
1. Sign in to the [Azure portal](https://portal.azure.com).
221
-
1. Enter _resource groups_ in the search box and select **Resource groups**.
222
-
223
-
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/search-box.png" alt-text="Screenshot of the Azure portal search box.":::
224
-
225
-
1. Select the deployment's resource group name.
226
-
1. Go to **Overview** and select **1 Failed**.
227
-
228
-
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/bicep-file-deployment-error.png" alt-text="Screenshot that highlights the link to failed deployment.":::
150
+
The deployment starts but fails with a message that the virtual network wasn't found. Notice in the portal that the deployment appears in the history.
229
151
230
-
1. From **Deployments** select **Error details**.
152
+
:::image type="content" source="media/quickstart-troubleshoot-bicep-deployment/view-deployment-history.png" alt-text="Screenshot of deployment history in portal.":::
231
153
232
-
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/bicep-file-deployment-error-details.png" alt-text="Screenshot of the failed deployments link to the error's details.":::
154
+
You can open the entry in the deployment history to get details about the error. The error also exists in the activity log.
233
155
234
-
The error message is the same as the deployment command's output:
156
+
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.
235
157
236
-
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/bicep-file-deployment-error-summary.png" alt-text="Screenshot of the deployment error's details.":::
237
-
238
-
### Activity log
239
-
240
-
You can also find the error in the resource group's activity logs. It takes a few minutes for the activity log to display the latest deployment information.
241
-
242
-
1. In the resource group, select **Activity log**.
243
-
1. Use the filters to find the log and select the log you want to view.
244
-
245
-
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/bicep-file-deployment-activity-log.png" alt-text="Screenshot of the resource group's activity log that highlights a failed deployment.":::
246
-
247
-
1. After you select the log, the details are shown.
:::image type="content" source="./media/quickstart-troubleshoot-bicep-deployment/bicep-file-deployment-activity-log-details.png" alt-text="Screenshot of the activity log details that shows a failed deployment's error message.":::
168
+
@description('Prefix for storage name.')
169
+
param prefixName string
250
170
251
-
### Fix the deployment error
171
+
var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'
252
172
253
-
The deployment error **No registered resource provider found** is caused by an incorrect API version. Use Visual Studio Code to change the API version to a valid value such as `2021-04-01`, and save the Bicep file. Follow the steps in [deploy the Bicep file](#deploy-the-bicep-file) to upload the Bicep file and rerun the deployment.
After the validation and deployment errors are fixed, the storage account is created. Go to the resource group's **Overview** to view the resource. The **Deployments** and **Activity log** will show a successful deployment.
0 commit comments