Bicep Troubleshooting

Every deployment fails at some point. A name is already taken, a permission is missing, or a region lacks a service. Good troubleshooting means finding the failing step quickly and reading the error message with a calm eye.

Think of a doctor visit. The doctor checks symptoms in a fixed order, from simple tests to deeper scans. Bicep problems respond to the same approach: start with the cheap checks and move toward the detailed ones.

Three Checkpoints

  1. Editor / compile      az bicep build        Catches syntax and type errors
            │
            ▼
  2. Validation            az deployment ... validate    Catches bad values and rules
            │
            ▼
  3. Deployment            az deployment ... create      Catches live Azure problems

Checkpoint 1: Compile Errors

Syntax mistakes surface before any Azure call. Missing quotes, wrong property names, and type mismatches appear in the editor with red underlines.

az bicep build --file main.bicep

Read the first error first. One early mistake often triggers a chain of later messages.

Checkpoint 2: Validation

The validate command sends the template to Azure without building anything. Azure checks parameter values, resource names, and permissions.

az deployment group validate \
  --resource-group rg-shop-dev \
  --template-file main.bicep \
  --parameters dev.bicepparam

Checkpoint 3: Deployment Errors

Some problems appear only during the real run. Azure returns an error code and a message for each failed resource. List the operations of a deployment to see the exact failure.

az deployment operation group list \
  --resource-group rg-shop-dev \
  --name main \
  --query "[?properties.provisioningState=='Failed']"

Common Error Codes

Error	Meaning	Typical Fix
StorageAccountAlreadyTaken	The storage name exists somewhere in Azure	Add uniqueString() to the name
AuthorizationFailed	The deploying identity lacks rights	Assign a suitable role at the right scope
InvalidTemplateDeployment	A rule or value in the template failed validation	Read the inner error details
LocationNotAvailableForResourceType	The region does not offer the service	Choose a supported region
QuotaExceeded	The subscription reached a size or count limit	Pick another size or request more quota
ResourceNotFound	A referenced resource does not exist yet	Check names, scopes, and dependencies

Unique Names with uniqueString

var storageName = 'st${uniqueString(resourceGroup().id)}'

The function creates a stable hash from the resource group ID, so the name stays the same on every run and differs across groups.

Check the Activity Log

The Azure portal's Activity Log shows each operation, who started it, and the full error text. Open the resource group, select Deployments, and click the failed entry for details.

A Simple Debugging Routine

Read the Innermost Message

Outer errors often say only "deployment failed". The inner details name the real cause.

Shrink the Problem

Comment out resources until the template passes, and restore them one at a time. The last resource added points to the cause.

Compare with the Portal

Create the same resource by hand in the portal and compare the settings with the template.

Keep Error Messages

Copy the full error text, including the correlation ID, into the team ticket. Support engineers use the ID to trace the failure inside Azure.

Summary

Troubleshooting follows three checkpoints: compile, validate, and deploy. The deployment operation list and the Activity Log reveal detailed errors. Unique names, correct roles, supported regions, and proper dependencies cure most common failures.