Setting the file. One moment.
Skill 47 · Azure Deployment Preflight
Subchapter 47.1
references/ERROR-HANDLING.mdMarkdown9 KBView on GitHub
This reference documents common errors during preflight validation and how to handle them.
Continue on failure. Capture all issues in the final report rather than stopping at the first error. This gives users a complete picture of what needs to be fixed.
Detection:
ERROR: Please run 'az login' to setup account.
ERROR: AADSTS700082: The refresh token has expiredExit Codes: Non-zero
Handling:
Report Entry:
#### ❌ Azure CLI Authentication Required
- **Severity:** Error
- **Source:** az cli
- **Message:** Not logged in to Azure CLI
- **Remediation:** Run `az login` to authenticate, then re-run preflight validation
- **Documentation:** https://learn.microsoft.com/en-us/cli/azure/authenticate-azure-cliDetection:
ERROR: not logged in, run `azd auth login` to loginHandling:
azd auth loginReport Entry:
#### ❌ Azure Developer CLI Authentication Required
- **Severity:** Error
- **Source:** azd
- **Message:** Not logged in to Azure Developer CLI
- **Remediation:** Run `azd auth login` to authenticate, then re-run preflight validationDetection:
AADSTS700024: Client assertion is not within its valid time range
AADSTS50173: The provided grant has expiredHandling:
Detection:
AuthorizationFailed: The client '...' with object id '...' does not have authorization
to perform action '...' over scope '...'Handling:
--validation-level ProviderNoRbacReport Entry:
#### ⚠️ Limited Permission Validation
- **Severity:** Warning
- **Source:** what-if
- **Message:** Full RBAC validation failed; using read-only validation
- **Detail:** Missing permission: `Microsoft.Resources/deployments/write` on scope `/subscriptions/xxx`
- **Recommendation:** Request Contributor role on the target resource group, or verify deployment permissions with your administratorDetection:
ResourceGroupNotFound: Resource group 'xxx' could not be found.Handling:
Report Entry:
#### ❌ Resource Group Does Not Exist
- **Severity:** Error
- **Source:** what-if
- **Message:** Resource group 'my-rg' does not exist
- **Remediation:** Create the resource group before deployment:
```bash
az group create --name my-rg --location eastus
### Subscription Access Denied
**Detection:**SubscriptionNotFound: The subscription ‘xxx’ could not be found. InvalidSubscriptionId: Subscription ‘…’ is not valid
**Handling:**
1. Note in report
2. Suggest checking subscription ID
3. List available subscriptions
---
## Bicep Syntax Errors
### Compilation Errors
**Detection:**/path/main.bicep(22,51) : Error BCP064: Found unexpected tokens /path/main.bicep(10,5) : Error BCP018: Expected the "=" character at this location
**Handling:**
1. Parse error output for line/column numbers
2. Include all errors in report (don't stop at first)
3. Continue to what-if (may provide additional context)
**Report Entry:**
```markdown
#### ❌ Bicep Syntax Error
- **Severity:** Error
- **Source:** bicep build
- **Location:** `main.bicep:22:51`
- **Code:** BCP064
- **Message:** Found unexpected tokens in interpolated expression
- **Remediation:** Check the string interpolation syntax at line 22
- **Documentation:** https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/diagnostics/bcp064Detection:
Error BCP091: An error occurred reading file. Could not find file '...'
Error BCP190: The module is not validHandling:
bicep restore is neededDetection:
Error BCP032: The value must be a compile-time constant
Error BCP035: The specified object is missing required propertiesHandling:
Detection:
'az' is not recognized as an internal or external command
az: command not foundHandling:
extension_cli_install tool to get installation instructions.Report Entry:
#### ⏭️ Azure CLI Not Installed
- **Severity:** Warning
- **Source:** environment
- **Message:** Azure CLI (az) is not installed or not in PATH
- **Remediation:** Install the Azure CLI <ADD INSTALLATION INSTRUCTIONS HERE>
- **Impact:** What-if validation using az commands was skippedDetection:
'bicep' is not recognized as an internal or external command
bicep: command not foundHandling:
az bicep buildReport Entry:
#### ⏭️ Bicep CLI Not Installed
- **Severity:** Warning
- **Source:** environment
- **Message:** Bicep CLI is not installed
- **Remediation:** Install Bicep CLI: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install
- **Impact:** Syntax validation was skipped; Azure will validate during what-ifDetection:
'azd' is not recognized as an internal or external command
azd: command not foundHandling:
azure.yaml exists, this is requiredDetection:
The deployment exceeded the nested template limit of 500Handling:
Detection:
templateLink references in nested deployments won't be visible in what-ifHandling:
Detection: Properties showing function names like [utcNow()] instead of values
Handling:
Detection:
Connection timed out
Request timed outHandling:
Detection:
SSL: CERTIFICATE_VERIFY_FAILED
unable to get local issuer certificateHandling:
When primary validation fails, attempt fallbacks in order:
Provider (full RBAC validation)
↓ fails with permission error
ProviderNoRbac (validation without write permission check)
↓ fails
Template (static syntax only)
↓ fails
Report all failures and skip what-if analysisAlways continue to generate the report, even if all validation steps fail.
When multiple errors occur, aggregate them logically:
Example:
## Issues
Found **3 errors** and **2 warnings**
### Errors (3)
1. [Bicep Syntax Error - main.bicep:22:51](#error-1)
2. [Bicep Syntax Error - main.bicep:45:10](#error-2)
3. [Resource Group Not Found](#error-3)
### Warnings (2)
1. [Limited Permission Validation](#warning-1)
2. [Nested Template Limit Reached](#warning-2)| Tool | Exit Code | Meaning |
|---|---|---|
| az | 0 | Success |
| az | 1 | General error |
| az | 2 | Command not found |
| az | 3 | Required argument missing |
| azd | 0 | Success |
| azd | 1 | Error |
| bicep | 0 | Build succeeded |
| bicep | 1 | Build failed (errors) |
| bicep | 2 | Build succeeded with warnings |