awesome-copilot/skills/azure-deployment-preflight/references/ERROR-HANDLING.md

Error Handling Guide

This reference documents common errors during preflight validation and how to handle them.

Core Principle

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.

---

Authentication Errors

Not Logged In (Azure CLI)

Detection:

ERROR: Please run 'az login' to setup account.
ERROR: AADSTS700082: The refresh token has expired

Exit Codes: Non-zero

Handling:

1. Note the error in the report
2. Include remediation steps
3. Skip remaining Azure CLI commands
4. Continue with other validation steps if possible

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-cli

Not Logged In (azd)

Detection:

ERROR: not logged in, run `azd auth login` to login

Handling:

1. Note the error in the report
2. Skip azd commands
3. Suggest azd auth login

Report 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 validation

Token Expired

Detection:

AADSTS700024: Client assertion is not within its valid time range
AADSTS50173: The provided grant has expired

Handling:

1. Note the error
2. Suggest re-authentication
3. Skip Azure operations

---

Permission Errors

Insufficient RBAC Permissions

Detection:

AuthorizationFailed: The client '...' with object id '...' does not have authorization 
to perform action '...' over scope '...'

Handling:

1. First attempt: Retry with --validation-level ProviderNoRbac
2. Note the permission limitation in the report
3. If ProviderNoRbac also fails, report the specific missing permission

Report 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 administrator

Resource Group Not Found

Detection:

ResourceGroupNotFound: Resource group 'xxx' could not be found.

Handling:

1. Note in report
2. Suggest creating the resource group
3. Skip what-if for this scope

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/bcp064

Module Not Found

Detection:

Error BCP091: An error occurred reading file. Could not find file '...'
Error BCP190: The module is not valid

Handling:

1. Note missing module
2. Check if bicep restore is needed
3. Verify module path

Parameter File Issues

Detection:

Error BCP032: The value must be a compile-time constant
Error BCP035: The specified object is missing required properties

Handling:

1. Note parameter issues
2. Indicate which parameters are problematic
3. Suggest fixes

---

Tool Not Installed

Azure CLI Not Found

Detection:

'az' is not recognized as an internal or external command
az: command not found

Handling:

1. Note in report
2. Provide installation instructions.

• If available use the Azure MCP extension_cli_install tool to get installation instructions.
• Otherwise look for instructions at https://learn.microsoft.com/en-us/cli/azure/install-azure-cli.

3. Skip az commands

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 skipped

Bicep CLI Not Found

Detection:

'bicep' is not recognized as an internal or external command
bicep: command not found

Handling:

1. Note in report
2. Azure CLI may have built-in Bicep - try az bicep build
3. Provide installation link

Report 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-if

Azure Developer CLI Not Found

Detection:

'azd' is not recognized as an internal or external command
azd: command not found

Handling:

1. If azure.yaml exists, this is required
2. Fall back to az CLI commands if possible
3. Note in report

---

What-If Specific Errors

Nested Template Limits

Detection:

The deployment exceeded the nested template limit of 500

Handling:

1. Note as warning (not error)
2. Explain affected resources show as "Ignore"
3. Suggest manual review

Template Link Not Supported

Detection:

templateLink references in nested deployments won't be visible in what-if

Handling:

1. Note as warning
2. Explain limitation
3. Resources will be verified during actual deployment

Unevaluated Expressions

Detection: Properties showing function names like [utcNow()] instead of values

Handling:

1. Note as informational
2. Explain these are evaluated at deployment time
3. Not an error

---

Network Errors

Timeout

Detection:

Connection timed out
Request timed out

Handling:

1. Suggest retry
2. Check network connectivity
3. May indicate Azure service issues

SSL/TLS Errors

Detection:

SSL: CERTIFICATE_VERIFY_FAILED
unable to get local issuer certificate

Handling:

1. Note in report
2. May indicate proxy or corporate firewall
3. Suggest checking SSL settings

---

Fallback Strategy

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 analysis

Always continue to generate the report, even if all validation steps fail.

---

Error Report Aggregation

When multiple errors occur, aggregate them logically:

1. Group by source (bicep, what-if, permissions)
2. Order by severity (errors before warnings)
3. Deduplicate similar errors
4. Provide summary count at the top

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)

---

Exit Code Reference

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