# Troubleshooting

## Common Issues

### AI Provider Connection Failures

**Copilot provider**: The default provider (`copilot`) connects to `api.enterprise.githubcopilot.com`. Failures typically indicate that GitHub Copilot is not enabled for the user's organization or that the authentication token has expired. The default model is `claude-sonnet-4` with a 480-second timeout. Dynamic model discovery via the `/models` endpoint supports Claude, GPT, and Gemini families. For large prompts, increase the timeout via `set COPILOT_TIMEOUT=600`.

**GitHub Models provider**: Requires a valid GitHub personal access token configured in `prototype.secrets.yaml` under `ai.github_models.api_key`. Verify the token has appropriate scopes and has not expired.

**Azure OpenAI provider**: Requires an Azure OpenAI endpoint and API key. Verify the endpoint URL, API key, and deployment name in the project configuration. Connection issues often stem from incorrect endpoint formatting or expired keys.

To check current AI configuration:

```bash
az prototype config get --key ai.provider
```

To switch providers:

```bash
az prototype config set --key ai.provider --value copilot
```

### Missing Prerequisites

**Terraform not installed**: The build and deploy stages require Terraform when `iac_tool` is set to `terraform`. Install via [terraform.io](https://www.terraform.io/downloads) and ensure the `terraform` binary is on your PATH.

**Bicep not installed**: Required when `iac_tool` is set to `bicep`. Install via `az bicep install` or download from the [Bicep releases](https://github.com/Azure/bicep/releases).

**GitHub CLI not installed**: Required for GitHub-based [backlog generation](Backlog-Generation.md) push operations. Install from [cli.github.com](https://cli.github.com/).

**Azure DevOps extension not installed**: Required for Azure DevOps backlog push operations. Install via `az extension add --name azure-devops`.

### Config File Corruption

If `prototype.yaml` contains legacy `DefaultStr` YAML tags, the config parser may fail. This typically occurs after upgrading from an earlier version. To resolve:

1. Open `prototype.yaml` in a text editor
2. Remove any `!DefaultStr` or similar custom tags
3. Save and retry the command

### Build Failures

Build failures trigger the QA remediation loop automatically. After the QA agent reviews generated code and finds issues, the system:

1. Identifies affected stages from the QA output
2. Regenerates those stages with QA findings appended as fix instructions
3. Re-runs QA review on the remediated code
4. Reports only remaining issues

If issues persist after remediation, they are tracked via the [escalation system](Escalation.md).

### Deploy Failures

Deploy failures route to the QA agent for diagnosis (see [Error Analysis](Error-Analysis.md)). Common deployment issues include:

- **Preflight check failures**: Missing Azure CLI login, incorrect subscription, missing resource providers. Run `az prototype deploy --status` to see preflight results.
- **Terraform/Bicep errors**: Syntax errors, API version mismatches, resource conflicts. Check the generated code in the project's `infra/` directory.
- **Timeout issues**: Large deployments may exceed default timeouts. Check Azure deployment status in the portal.

Rollback is available for failed deployments, with ordered enforcement -- you cannot rollback stage N while stage N+1 is still deployed. Use `az prototype deploy --rollback-info` to see rollback instructions.

### Permission Issues

**Subscription access**: Verify you have Contributor or Owner role on the target subscription. Run `az account show` to confirm the active subscription.

**Cross-tenant deployment**: Use `--tenant` to specify the target tenant ID. For service principal authentication, provide `--service-principal` along with `--client-id`, `--client-secret`, and `--tenant-id`. Credentials route to `prototype.secrets.yaml` automatically.

**Tenant mismatch**: The deploy preflight checks warn if the active Azure CLI tenant differs from the target tenant configured in the project.

## Diagnostic Commands

### Overall Status

```bash
az prototype status --detailed
```

Shows per-stage status across all stages (init, design, build, deploy) with expanded details.

### Design Status

```bash
az prototype design --status
```

Shows current discovery status: open items, confirmed items, scope decisions (in-scope, out-of-scope, deferred).

### Build Status

```bash
az prototype build --status
```

Shows current build progress: completed stages, pending stages, and any recorded issues.

### Deploy Status

```bash
az prototype deploy --status
```

Shows current deployment progress: deployed stages, failed stages, preflight results.

### Deploy Outputs

```bash
az prototype deploy --outputs
```

Shows captured deployment outputs from Terraform or Bicep (resource IDs, endpoints, connection strings).

### Rollback Information

```bash
az prototype deploy --rollback-info
```

Shows rollback instructions based on deployment history, including which stages can be safely rolled back.

## Reset Options

When a stage is in a bad state, you can reset it and start fresh:

### Reset Design

```bash
az prototype design --reset
```

Clears design state (discovery conversation, architecture output) and starts fresh. Does not affect build or deploy state.

### Reset Build

```bash
az prototype build --reset
```

Clears build state (generated code, QA results, deployment plan) and starts fresh. Does not affect design state but deploy state may become stale.

### Reset Deploy

```bash
az prototype deploy --reset
```

Clears deploy state (deployment history, captured outputs, rollback tracking) and starts fresh. Does not destroy deployed Azure resources -- only clears local tracking state.

## FAQ

### Can I switch IaC tools mid-project?

Switching between Terraform and Bicep after the build stage requires resetting the build state (`az prototype build --reset`) and rebuilding. The design stage is IaC-agnostic, so design state is preserved. Change the IaC tool via:

```bash
az prototype config set --key iac_tool --value bicep
az prototype build --reset
az prototype build
```

### Can I switch AI providers?

Yes. Change the provider at any time:

```bash
az prototype config set --key ai.provider --value copilot
```

Configure provider-specific settings (API keys, endpoints) in `prototype.secrets.yaml` or via `az prototype config set`. Existing stage state is preserved -- the new provider is used for subsequent AI calls.

### How do I re-run a stage?

All stages are re-entrant. Simply run the stage command again:

```bash
az prototype design              # Re-enters discovery or regenerates architecture
az prototype build               # Resumes or re-runs build
az prototype deploy              # Re-runs deployment
```

To force a completely fresh start for a stage, use `--reset` first.

### Where are generated files stored?

- **Project config**: `prototype.yaml` and `prototype.secrets.yaml` in the project root
- **State files**: `.prototype/state/` directory (design, build, deploy, backlog, escalation YAML files)
- **Generated infrastructure**: project root, typically in `infra/` or stage-specific directories
- **Generated application code**: project root, in service-specific directories
- **Custom agents**: `.prototype/agents/` directory
- **Custom MCP handlers**: `.prototype/mcp/` directory

### How do I use a service principal?

For automated or cross-tenant deployments:

```bash
az prototype deploy \
  --service-principal \
  --client-id <app-id> \
  --client-secret <secret> \
  --tenant-id <tenant-id>
```

Alternatively, configure credentials in `prototype.secrets.yaml`:

```yaml
deploy:
  service_principal:
    client_id: "<app-id>"
    client_secret: "<secret>"
    tenant_id: "<tenant-id>"
```

Then deploy with just the flag:

```bash
az prototype deploy --service-principal
```

## Debug Logging

For detailed diagnostic information, enable debug logging:

```bash
# Windows
set DEBUG_PROTOTYPE=true
az prototype design --context "..."

# Linux/macOS
DEBUG_PROTOTYPE=true az prototype design --context "..."
```

This creates a timestamped log file `debug_YYYYMMDDHHMMSS.log` in the project directory. The log captures:

- **Session context**: Python version, OS, AI provider, model, timeout, project path
- **Every AI call**: system message sizes, user content (first 2000 chars), model, temperature, max_tokens
- **Every AI response**: elapsed time, response content (first 2000 chars), token counts
- **Every state mutation**: topic status changes, discovery state saves
- **Every decision branch**: reentry vs fresh path, context hash matches, artifact deltas
- **Every slash command**: command name, current topic, exchange count
- **Every error**: full Python traceback

See [Debug Logging](Debug-Logging) for the full format reference.

## Getting Help

File issues at the repository: [Azure/azext-prototype](https://github.com/Azure/azext-prototype/issues)

Include the following in bug reports:

- Output of `az prototype status --detailed`
- The stage and command that failed
- Error messages or log output
- Azure CLI version (`az version`)
- Debug log file (if available) — see Debug Logging above

## Related

- [Error Analysis](Error-Analysis.md) -- AI-powered error diagnosis
- [Escalation](Escalation.md) -- automated escalation chain for blocked tasks
- [Knowledge System](Knowledge-System.md) -- runtime documentation and web search
- [MCP Integration](MCP-Integration.md) -- external tool configuration issues