Troubleshooting Guide

Troubleshooting Guide

Common issues and solutions for Agentic InfraOps

Agent Personas Quick Reference

Quick Decision Tree

%%{init: {'theme':'neutral'}}%%
flowchart TD
    START["Problem?"] --> TYPE{"What type?"}
    
    TYPE -->|"Agent won't start"| AGENT
    TYPE -->|"Skill not activating"| SKILL
    TYPE -->|"Deployment fails"| DEPLOY
    TYPE -->|"Validation errors"| VALIDATE
    TYPE -->|"Azure auth"| AUTH
    
    AGENT --> AGENT1["Check: Ctrl+Shift+A<br/>shows agent list?"]
    AGENT1 -->|No| AGENT2["Reload VS Code window"]
    AGENT1 -->|Yes| AGENT3["Agent missing from list?<br/>Check .agent.md exists"]
    
    SKILL --> SKILL1["Using trigger keywords?"]
    SKILL1 -->|No| SKILL2["Add explicit keywords<br/>or reference skill by name"]
    SKILL1 -->|Yes| SKILL3["Check SKILL.md file<br/>for correct triggers"]
    
    DEPLOY --> DEPLOY1["Run preflight first:<br/>deploy agent preflight check"]
    
    VALIDATE --> VALIDATE1["Run: npm run validate"]
    
    AUTH --> AUTH1["Run: az login"]

    style START fill:#e1f5fe
    style AGENT fill:#fff3e0
    style SKILL fill:#f3e5f5
    style DEPLOY fill:#c8e6c9
    style VALIDATE fill:#fce4ec
    style AUTH fill:#fff9c4

Common Issues

1. Agent Not Appearing in List

Symptom: Ctrl+Shift+A doesn't show expected agent.

Causes:

• Agent file not in .github/agents/ folder
• YAML front matter syntax error
• VS Code extension not loaded

Solutions:

# Check agent files exist
ls -la .github/agents/*.agent.md

# Validate YAML front matter
head -20 .github/agents/requirements.agent.md

Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

1.5. Conductor/Subagent Invocation Not Working (VS Code 1.109+)

Symptom: The InfraOps Conductor (🎼 Maestro) doesn't delegate to specialized agents. Responses are instant, no terminal commands execute, no files are created.

Root Cause: The chat.customAgentInSubagent.enabled setting is not enabled in User Settings.

Solutions:

1. Enable in User Settings (not just workspace):

   • Press Ctrl+, → Search for customAgentInSubagent
   • Check the box to enable
   • OR add to User Settings JSON:

   {
     "chat.customAgentInSubagent.enabled": true
   }
   

2. Verify agents have agent tool:

   grep -l '"agent"' .github/agents/*.agent.md
   # Should list all main agents
   

3. Verify agents have wildcard agents array:

   grep 'agents:.*\["\*"\]' .github/agents/*.agent.md
   # Should show agents: ["*"] in each file
   

4. Use Chat Diagnostics:

   • Right-click in Chat view → "Diagnostics"
   • Check all agents are loaded correctly

Note: Workspace settings (.vscode/settings.json) may not be sufficient for experimental features. User settings take precedence.

2. Skill Not Activating Automatically

Symptom: Prompt doesn't trigger expected skill.

Causes:

• Missing trigger keywords in prompt
• Skill file not in .github/skills/ folder
• Description doesn't match user intent

Solutions:

Use explicit skill invocation:

"Use the azure-diagrams skill to create a diagram"

Check skill triggers in SKILL.md:

cat .github/skills/azure-diagrams/SKILL.md | head -30

3. Deployment Fails with Azure Policy Error

Symptom: az deployment group create fails with policy violation.

Common policies:

Run preflight check:

"Run deployment preflight for {project}"

4. Bicep Build Errors

Symptom: bicep build fails.

Common causes:

# Check Bicep CLI version
bicep --version  # Should be 0.30+

# Validate syntax
bicep lint infra/bicep/{project}/main.bicep

AVM module not found:

# Restore modules from registry
bicep restore infra/bicep/{project}/main.bicep

5. Azure Authentication Issues

Symptom: "Not logged in" or subscription errors.

Solutions:

# Login to Azure
az login

# Set correct subscription
az account set --subscription "<subscription-id>"

# Verify
az account show

For Service Principal:

az login --service-principal -u $AZURE_CLIENT_ID -p $AZURE_CLIENT_SECRET --tenant $AZURE_TENANT_ID

6. Artifact Validation Failures

Symptom: npm run validate fails.

Causes:

• Missing required H2 headings
• Headings in wrong order
• Using prohibited references

Check specific artifact:

# See validation rules
cat scripts/validate-artifact-templates.mjs | grep -A20 "ARTIFACT_HEADINGS"

Fix order issues: Compare with template:

diff -u .github/templates/01-requirements.template.md agent-output/{project}/01-requirements.md

7. MCP Server Not Responding

Symptom: Azure Pricing MCP calls fail.

Solutions:

# Check MCP configuration
cat .vscode/mcp.json

# Verify Python environment
python3 --version  # Should be 3.10+

# Install dependencies
cd mcp/azure-pricing-mcp && pip install -r requirements.txt

8. Devcontainer Build Fails

Symptom: Dev container won't start.

Common causes:

• Docker not running
• Port conflicts
• Outdated base image

Solutions:

# Rebuild without cache
# In VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container Without Cache"

Check Docker is running:

docker ps

9. Git Push Fails with Lefthook Errors

Symptom: Pre-commit hooks fail.

Common hooks:

Skip hooks temporarily (not recommended):

git commit --no-verify -m "fix: temporary"

10. Handoff Prompt Not Working

Symptom: Agent handoff button does nothing.

Causes:

• Handoff target agent doesn't exist
• YAML handoffs section malformed

Check handoffs syntax:

handoffs:
  - label: "Create WAF Assessment"
    agent: architect
    prompt: "Assess requirements for WAF..."
    send: true

Ensure target agent exists:

ls .github/agents/architect.agent.md

Diagnostic Commands

Environment Check

# All-in-one status
echo "=== Bicep ===" && bicep --version
echo "=== Azure CLI ===" && az version --output table
echo "=== Node ===" && node --version
echo "=== Python ===" && python3 --version
echo "=== Git ===" && git --version

Workspace Validation

# Validate all artifacts
npm run validate

# Check for broken links
npm run check-links

# Lint markdown
npm run lint:md

Azure Status

# Current subscription
az account show --output table

# List resource groups
az group list --output table

# Check deployments
az deployment group list -g {resource-group} --output table

Getting Help

1. Check scenarios: scenarios/ folder has working examples
2. Read agent definitions: .github/agents/*.agent.md
3. Check skill files: .github/skills/*/SKILL.md
4. Review templates: .github/templates/

Still Stuck?

Use the diagnose agent (🔍 Sentinel):

Ctrl+Shift+A → diagnose
"My bicep-code agent isn't generating valid templates"

Or start the InfraOps Conductor (🎼 Maestro) for a guided workflow:

Ctrl+Shift+I → InfraOps Conductor
"Help me troubleshoot my Azure deployment"