Problem

PowerShell hook/script failures account for ~6,347 errors (4.96%) over 90 days, making it the 4th largest error category. These are reported as tool.pwsh.failed with an exit code but no actionable guidance on how to fix common issues. AI templates are hit harder at 6.59% due to heavier reliance on PowerShell hooks for model deployment and data seeding.

Current Behavior

PowerShell hook failures are classified in internal/cmd/errors.go (lines 129-140) as tool.pwsh.failed with the exit code stored in telemetry. The user sees the exit code and stderr output but no structured guidance on common fixes.

Proposed Solution

1. When a PowerShell hook fails, inspect the script for Continue = 'Stop'. If absent, suggest adding it: Tip: Add Continue = 'Stop' at the top of your hook script to ensure errors are caught and surfaced properly.
2. Detect common failure patterns in stderr output and provide targeted suggestions:
   • Missing PowerShell modules (Import-Module: The specified module was not loaded): Suggest installing the required module
   • Azure authentication timeout: Suggest re-running azd auth login
   • Az module not found: Suggest Install-Module Az -Scope CurrentUser
   • Permission denied: Suggest checking execution policy with Get-ExecutionPolicy
3. Consider adding a --validate-hooks flag or pre-deployment step that checks hook scripts for common issues before deployment begins
4. For AI templates specifically, validate that Az.CognitiveServices and Az.Search modules are available when hooks reference them

Data Reference

Source: AzdProvisionErrorsByTemplate + AzdDeploymentErrorsByTemplate (DevCli on ddazureclients)

• PowerShell Script Error: 6,347 (4.96%)
• AI templates: 6.59% (1,373 errors), Awesome-azd: 2.97% (724 errors)
• Error code: tool.pwsh.failed