Actionable error guidance when deployment pipeline steps fail
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
## 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
- #16090 — Parameter experience improvements (parameter validation failures are a subset of this)
- #16063 — Unified resource introspection (error context from deployed environments)
Contributor guide
Assessment
This issue has not been assessed yet.