Troubleshooting

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:

az prototype config get --key ai.provider

To switch providers:

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

GitHub CLI not installed: Required for GitHub-based backlog generation push operations. Install from 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.

Deploy Failures

Deploy failures route to the QA agent for diagnosis (see Error Analysis). 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

az prototype status --detailed

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

Design Status

az prototype design --status

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

Build Status

az prototype build --status

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

Deploy Status

az prototype deploy --status

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

Deploy Outputs

az prototype deploy --outputs

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

Rollback Information

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

az prototype design --reset

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

Reset Build

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

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:

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:

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:

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:

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

Alternatively, configure credentials in prototype.secrets.yaml:

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

Then deploy with just the flag:

az prototype deploy --service-principal

Debug Logging

For detailed diagnostic information, enable debug logging:

# 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 for the full format reference.

Getting Help

File issues at the repository: Azure/azext-prototype

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 -- AI-powered error diagnosis
• Escalation -- automated escalation chain for blocked tasks
• Knowledge System -- runtime documentation and web search
• MCP Integration -- external tool configuration issues