aspire doctor command

Name

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

Synopsis

Aspire CLI

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.

Nota

The aspire doctor command replaces the hidden aspire setup command. If you previously used aspire setup or aspire setup --force, use aspire doctor instead. The aspire setup command is still available for backward compatibility but is hidden from help output.

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)
• Development tools checks: When VS Code is detected, reports whether the Aspire VS Code extension is installed

Nota

The development tools check only runs when VS Code is detected, using the same signals the CLI already relies on: the TERM_PROGRAM=vscode environment variable (VS Code’s integrated terminal) or code/code-insiders on PATH. If VS Code isn’t detected, the check is skipped and adds no output. When VS Code is detected but the Aspire extension (microsoft-aspire.aspire-vscode) isn’t installed, aspire doctor reports a warning with a link to install it from the Marketplace. When the extension is already installed, the check passes.

Nota

On Linux, aspire doctor reports a warning when certutil is unavailable. Aspire uses certutil to query and update the NSS certificate databases used by Firefox and Chromium browsers, so without it browser certificate trust may be incomplete. Install certutil from your distribution’s NSS tools package, for example libnss3-tools, to resolve the warning.

Nota

On Linux, aspire doctor also checks the OpenSSL development certificate cache under the dev-certs trust directory. It reports a warning when the cache is missing the current HTTPS development certificate, is missing the subject-hash link OpenSSL uses to look up certificates by directory, or contains certificate files that can’t be read (for example, because they’re corrupt). In each case, aspire doctor recommends running aspire certs clean followed by aspire certs trust to remove stale or corrupt certificates and regenerate trusted development certificates. If the openssl command isn’t installed, the fix suggestion also tells you to install it first.

Nota

Environment checks time out after 30 seconds each or two minutes in aggregate, and installation discovery times out after 30 seconds. If a timeout occurs, the aspire doctor result includes a warning.

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:

Aspire CLI

Checking Aspire environment...

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

Aspire
  ✅ Aspire CLI version 13.5.3

AppHost
  ✅ AppHost version 13.5.3 (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 CLI

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

AppHost
  ✅ AppHost version 13.5.3 (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.

On Linux, when certutil is not installed, the Environment section reports a warning instead of failing the check:

Aspire CLI

Environment
  ✅ Operating system: Linux Ubuntu 24.04
  ⚠️ certutil is not available; browser certificate trust may be incomplete
       Install certutil from your distribution's NSS tools package (for example, libnss3-tools).

On Linux, when the OpenSSL development certificate cache is stale, missing the current certificate, or contains unreadable certificate files, the Environment section reports a warning with a suggestion to clean and re-trust the certificate:

Aspire CLI

Environment
  ✅ Operating system: Linux Ubuntu 24.04
  ⚠️ OpenSSL HTTPS development certificate cache is missing the current certificate
       Run 'aspire certs clean' and then 'aspire certs trust' to remove stale or corrupt certificates and regenerate trusted development certificates.

When only Podman is running:

Aspire CLI

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:

Aspire CLI

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).

When VS Code is detected but the Aspire extension isn’t installed, the Development tools section reports a warning:

Aspire CLI

Development tools
  ⚠️ VS Code is installed, but the Aspire extension is not installed
       Install the Aspire extension from the VS Code Marketplace for an integrated Aspire experience.

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.

JSON output

{
  "checks": [
    {
      "category": "aspire",
      "name": "cli-version",
      "status": "pass",
      "message": "Aspire CLI version 13.5.3",
      "metadata": {
        "currentVersion": "13.5.3"
      }
    },
    {
      "category": "apphost",
      "name": "apphost-version",
      "status": "pass",
      "message": "AppHost version 13.5.3 (MyApp.AppHost.csproj)",
      "metadata": {
        "appHostPath": "MyApp.AppHost.csproj",
        "version": "13.5.3"
      }
    },
    {
      "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 VS Code is detected, the checks include a devtools category entry named vscode-extension. It reports "status": "warning" when the Aspire VS Code extension isn’t installed, and "status": "pass" when it is. Its metadata includes vsCodeInstalled, extensionInstalled, and extensionId:

JSON output

{
  "category": "devtools",
  "name": "vscode-extension",
  "status": "warning",
  "message": "VS Code is installed, but the Aspire extension is not installed",
  "fix": "Install the Aspire extension from the VS Code Marketplace for an integrated Aspire experience.",
  "link": "https://aka.ms/aspire/vscode-extension",
  "metadata": {
    "vsCodeInstalled": true,
    "extensionInstalled": false,
    "extensionId": "microsoft-aspire.aspire-vscode"
  }
}

This check is omitted entirely when VS Code isn’t detected on the machine.

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

JSON output

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

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.

See also

• aspire command
• aspire run command
• Aspire CLI overview