microsoft / microsoft/aspire

[VS Code] Make Aspire errors specific and actionable

Open
#19,504 1 comment 0 reactions 0 assignees View on GitHub
area-vscode needs-design
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

The Aspire pane currently has two static error states:

- A compatibility message that says Aspire CLI and Aspire.Hosting 13.2.0 or newer are required, with actions to update the CLI and refresh.
- A generic message that says the pane could not load AppHost data and directs users to the Aspire Extension output, with only a refresh action.

Internally, the extension retains substantially more specific error information. Failures can include:

- The Aspire CLI is missing or its configured path is invalid.
- The installed CLI is too old to support the required command.
- The AppHost references an incompatible Aspire.Hosting version.
- No container runtime is available.
- `aspire ls`, `aspire ps`, or `aspire describe` failed.
- AppHost discovery or output parsing failed.

These failures are reduced to the same generic UI. The compatibility state also combines CLI and AppHost incompatibility but only offers to update the CLI.

The generic message instructs users to open the Aspire Extension output, but the extension does not provide a user-facing command or link that opens that output channel directly.

Error rendering also relies on the view's welcome content. That is primarily an empty-view surface, so a refresh failure may not be visible when previously loaded or stale tree items remain.

### Describe the solution you'd like

Surface a concise, classified error in the Aspire pane and provide recovery actions appropriate to its cause.

Suggested recovery behavior:

| Failure | Actions |
|---|---|
| CLI missing or path invalid | **Install Aspire CLI**, **Configure CLI path**, **Open Aspire output**, **Retry** |
| CLI version unsupported | **Update Aspire CLI**, **Open Aspire output**, **Retry** |
| AppHost version unsupported | **Update AppHost**, **Open AppHost source**, **Open Aspire output**, **Retry** |
| Environment or prerequisite failure | **Run Aspire Doctor**, **Open Aspire output**, **Retry** |
| Discovery, configuration, or unknown failure | **Show details**, **Run Aspire Doctor**, **Open Aspire output**, **Retry** |

Requirements:

- Display a bounded, user-readable summary of the actual failure rather than only a generic message.
- Keep full diagnostic output in the Aspire Extension output channel.
- Add an **Open Aspire output** command that focuses that channel directly.
- Add a minimal **Run Aspire Doctor** command that runs `aspire doctor` in the Aspire terminal. A custom doctor-results UI is out of scope.
- Reuse the existing CLI installation, CLI update, AppHost update, settings, and refresh commands where applicable.
- Do not offer **Run Aspire Doctor** when no CLI can be resolved.
- Do not offer an AppHost update action when no target AppHost is known.
- Keep errors visible when existing or stale tree items remain.
- Retry the operation appropriate to the current workspace/global view.
- Localize all user-facing text.
- Add unit and end-to-end coverage for missing CLI, CLI compatibility, AppHost compatibility, environment failure, generic discovery failure, and errors occurring after data was previously loaded.

### Additional context

N/A

Contributor guide

Open the contributing guide

Research direction

Start by tracing the Aspire pane's existing compatibility and generic error states, then inspect the current CLI installation, update, AppHost update, settings, and refresh commands. Add classified recovery actions and the Open Aspire output and Run Aspire Doctor commands, keep errors visible over existing tree items, localize the text, and add unit and end-to-end coverage for the listed failure cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
vscode
Domain
developer-experience, devtools
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.