microsoft / microsoft/aspire

Actionable error guidance when deployment pipeline steps fail

Open
#16,171 0 comments 2 reactions 0 assignees View on GitHub
area-deployment
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.