aspire doctor command

Name

aspire doctor - Check the Aspire development environment for common issues.

Synopsis

aspire doctor [options]

Description

The aspire doctor command runs a series of diagnostic checks to verify that your development environment is properly configured for Aspire development. It checks prerequisites such as the .NET SDK, container runtime, and environment settings.

This command is useful for troubleshooting when you encounter issues with Aspire or when setting up a new development environment. The checks are grouped by category:

Aspire checks: Reports the current Aspire CLI version and whether a newer CLI version is available, and suggests running aspire update when a newer one is available
AppHost checks: Reports the AppHost Aspire SDK version when an AppHost project is present in the current directory
SDK checks: Verifies .NET SDK installation and version requirements
Container checks: Validates container runtime (Docker and/or Podman) availability, running status, and version. Reports which runtime is active and why (explicit configuration, auto-detected default, or auto-detected only runtime running)
Environment checks: Reports operating system information (type, version, and Linux distro details when available) and validates environment variables and other settings, including the JavaScript toolchain required by TypeScript AppHosts (npm, pnpm, Yarn, or Bun)

The command displays results with clear status indicators:

✅ (green) - Check passed
⚠️ (yellow) - Warning (non-blocking issue)
❌ (red) - Check failed (blocking issue)

If any checks fail, the command provides suggestions for how to fix the issues and links to relevant documentation.

Options

The following options are available:

--format <Table|Json>

Output format (Table or Json). Use Json for automation scenarios or when you need to parse the results programmatically. Defaults to Table.
-?, -h, --help

Prints help and usage documentation for the available commands and options.
-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>

Set the minimum log level for console output. Use this option to increase diagnostics while troubleshooting or reduce output in scripted runs.
--non-interactive

Run the command in non-interactive mode, disabling all interactive prompts and spinners.
--nologo

Suppress the startup banner and telemetry notice.
--banner

Display the animated Aspire CLI welcome banner.
--wait-for-debugger

Wait for a debugger to attach before running a command.

Examples

Run diagnostic checks on your development environment:
Aspire CLI
```
aspire doctor
```
Run diagnostic checks with JSON output:
Aspire CLI
```
aspire doctor --format Json
```

Sample output

When you run aspire doctor from a directory containing an AppHost project, you see output similar to the following:

Checking Aspire environment...

Aspire Environment Check
========================

Aspire
  ✅ Aspire CLI version 13.5.0

AppHost
  ✅ AppHost version 13.5.0 (MyApp.AppHost.csproj)

.NET SDK
  ✅ .NET 10.0.203 installed (arm64)

Container Runtime
  ✅ Docker v28.5.1: running (auto-detected (default)) ← active

Environment
  ✅ Operating system: macOS 15.5.0
  ✅ HTTPS development certificate is trusted

Summary: 6 passed, 0 warnings, 0 failed

After the summary, table output also includes an Aspire CLI Installations table that lists discovered CLI binaries with their path, version, channel, install route, and PATH status.

When the CLI is out of date, the Aspire section shows a warning with the latest available version and a suggestion to run aspire update:

Aspire
  ⚠️ Aspire CLI version 13.5.0-dev is out of date. Latest version is 13.5.0-preview.1.26262.10
       Run 'aspire update' to update Aspire CLI.

AppHost
  ✅ AppHost version 13.5.0 (MyApp.AppHost.csproj)

This warning snippet is abbreviated. In complete table output, a summary follows the check results. When any warning or failure is present, Aspire also prints For detailed prerequisites: https://aka.ms/aspire-prerequisites. Some CLI and AppHost version messages include an inline (channel: <name>) suffix; the same channel data appears in JSON metadata as identityChannel, latestVersionChannel, or pinnedChannel when available.

When only Podman is running:

Container Runtime
  ✅ Podman v5.3.0: running (auto-detected (only runtime running)) ← active
  ❌ Docker is not installed

When you set ASPIRE_CONTAINER_RUNTIME=podman, Aspire honors the explicit configuration and Podman becomes active even when Docker is also running:

Container Runtime
  ✅ Podman v5.3.0: running (explicit configuration) ← active
  ✅ Docker v27.3.1: running (available)

The active runtime is annotated with ← active. Other detected runtimes are shown with (available).

Exit codes

The command returns the following exit codes:

Exit code	Description
`0`	All checks passed (warnings are allowed)
`1`	One or more checks failed

JSON output format

When using the --format Json option, the output includes a structured response with all check results, a summary, and discovered Aspire CLI installations. The following example is abbreviated to focus on selected checks; actual output includes an entry for every check and can include additional metadata, such as updateCommand, identityChannel, latestVersionChannel, and pinnedChannel.

{
  "checks": [
    {
      "category": "aspire",
      "name": "cli-version",
      "status": "pass",
      "message": "Aspire CLI version 13.5.0",
      "metadata": {
        "currentVersion": "13.5.0"
      }
    },
    {
      "category": "apphost",
      "name": "apphost-version",
      "status": "pass",
      "message": "AppHost version 13.5.0 (MyApp.AppHost.csproj)",
      "metadata": {
        "appHostPath": "MyApp.AppHost.csproj",
        "version": "13.5.0"
      }
    },
    {
      "category": "environment",
      "name": "operating-system",
      "status": "pass",
      "message": "Operating system: Linux Ubuntu 24.04",
      "metadata": {
        "osType": "Linux",
        "displayName": "Linux Ubuntu",
        "version": "24.04",
        "description": "Ubuntu 24.04.2 LTS"
      }
    },
    {
      "category": "sdk",
      "name": "dotnet-sdk",
      "status": "pass",
      "message": ".NET 10.0.203 installed (arm64)"
    }
  ],
  "summary": {
    "passed": 6,
    "warnings": 0,
    "failed": 0
  }
}

When the CLI is out of date, the cli-version check has "status": "warning" and the metadata includes the latest available version:

{
  "category": "aspire",
  "name": "cli-version",
  "status": "warning",
  "message": "Aspire CLI version 13.5.0-dev is out of date. Latest version is 13.5.0-preview.1.26262.10",
  "fix": "Run 'aspire update' to update Aspire CLI.",
  "metadata": {
    "currentVersion": "13.5.0-dev",
    "latestVersion": "13.5.0-preview.1.26262.10"
  }
}

The apphost-version check is only present in the JSON output when an AppHost project is discovered in the current directory.

The operating-system check is always present and includes the following metadata fields:

Field	Description
`osType`	The platform family: `Windows`, `macOS`, or `Linux`.
`displayName`	A human-readable OS name, for example `Windows`, `macOS`, or `Linux Ubuntu`.
`version`	The OS version string. On Linux this is the `VERSION_ID` from `/etc/os-release` when available; on Windows and macOS it is the value from `Environment.OSVersion`.
`description`	A longer description of the OS. On Linux this is the `PRETTY_NAME` value from `/etc/os-release` (for example `Ubuntu 24.04.2 LTS`); on other platforms it is the runtime OS description string.