Error Analysis - Azure/az-prototype GitHub Wiki

Error Analysis

Overview

The error analysis command provides AI-powered diagnosis of errors, failures, and unexpected behavior encountered during prototype development and deployment. It implements the QA-first routing principle: all errors are routed to the qa-engineer agent, which owns the full diagnostic lifecycle including evidence gathering, log analysis, and root cause identification.

For persistent or unresolvable issues, the system integrates with the escalation chain.

Command

az prototype analyze error --input INPUT
Parameter Type Description
--input string (required) Error input to analyze. Accepts an inline error string, a path to a log file, or a path to a screenshot image.
--json / -j flag Output machine-readable JSON instead of formatted display.

Input Types

The --input parameter accepts three types of input, detected automatically:

Inline Error String

Pass an error message directly as a quoted string. Useful for quick diagnosis of a specific error.

az prototype analyze error --input "Error: ResourceGroupNotFound - Resource group 'rg-myapp' could not be found"

Log File Path

Pass a path to a log file. The QA agent reads the file contents and analyzes the full log for errors, warnings, and root causes.

az prototype analyze error --input ./terraform.log

Screenshot Image

Pass a path to a screenshot image (PNG, JPG, etc.). The QA agent uses vision capabilities to analyze the screenshot, identify error messages, and diagnose the issue.

az prototype analyze error --input ./error-screenshot.png

QA-First Routing

Error analysis follows the agent governance principle that all errors, failures, and unexpected behavior must route to qa-engineer first. The QA agent:

  1. Gathers evidence -- examines the error message, log content, or screenshot
  2. Analyzes context -- considers the current project configuration, design, and build state
  3. Identifies root cause -- determines what went wrong and why
  4. Recommends resolution -- provides actionable steps to fix the issue

The QA agent has web search enabled (see Knowledge System), so it can look up Microsoft Learn documentation when diagnosing unfamiliar errors.

If the QA agent cannot resolve the issue and an escalation tracker is available, it records the blocker automatically for escalation.

Vision Support

When the input is an image file, the extension uses the AI provider's vision capabilities to analyze screenshots. This is particularly useful for:

  • Azure Portal error dialogs
  • Deployment failure screens
  • CLI output screenshots shared by team members
  • Browser-based application errors

The AIMessage.content field supports both string and list forms; the list form holds OpenAI-compatible vision content arrays with base64-encoded image data.

Examples

Analyze an inline error:

az prototype analyze error --input "TerraformError: Error creating AzureRM Resource Group: unexpected status 403"

Analyze a Terraform log file:

az prototype analyze error --input ./infra/terraform.log

Analyze a deployment failure screenshot:

az prototype analyze error --input ./screenshots/deploy-failure.png

Get JSON output for programmatic consumption:

az prototype analyze error --input "connection refused" --json

Related