Azure Deployment Preflight

# 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:**
```markdown
#### ❌ 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:**
```markdown
#### ❌ 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:**
```markdown
#### ⚠️ 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:**
```markdown
#### ❌ 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: