Actionable error guidance when deployment pipeline steps fail

[spboyer]

Problem

When aspire deploy fails — due to authentication issues, quota limits, naming conflicts, permission errors, or infrastructure provisioning failures — the user receives raw Azure SDK exceptions or ARM error responses with no guidance on what went wrong or how to recover.

For example:

• An authentication failure surfaces as an AuthenticationFailedException stack trace rather than telling the user to run az login
• A quota exceeded error shows the ARM error code and message but does not suggest requesting a quota increase or trying a different region
• A resource name conflict gives the API response but does not explain that the name is globally unique and must be changed
• A missing role assignment fails deep into a multi-minute deployment with no indication of which permission is needed or how to grant it
• A Bicep validation error shows the template error but does not help the user understand which resource definition in their AppHost caused it

Impact

• Wasted time — Users must copy error messages into search engines or documentation to understand what happened and how to fix it
• Deployment abandonment — New users encountering opaque errors during their first deploy may give up rather than diagnose
• CI/CD debugging — In non-interactive pipelines, raw exceptions in logs are especially hard to act on without contextual suggestions
• Agent workflows — AI coding agents that trigger deployments cannot interpret raw exceptions to suggest recovery steps without structured error context

Current State

• Pipeline steps report CompletedWithError status with error messages via the backchannel
• The pipeline summary shows failed steps but not why they failed or what to do about it
• No structured error categorization exists (auth vs quota vs naming vs permissions vs networking)
• No mechanism to attach recovery suggestions, relevant documentation links, or corrective actions to errors
• The MCP tool surface has no error diagnosis capability for agents

What Would Be Valuable

Users (and agents) should receive clear, actionable guidance when deployment fails:

• What went wrong — categorized in human terms, not just the raw API error
• Why it happened — context about which resource or step triggered the failure
• How to fix it — specific steps, commands, or configuration changes to recover
• Where to learn more — links to relevant documentation when applicable

Related Issues

• Improve parameter experience during deployment #16090 — Parameter experience improvements (parameter validation failures are a subset of this)
• Unified resource introspection for local and deployed environments #16063 — Unified resource introspection (error context from deployed environments)