Aspire troubleshooting guide

Having issues getting started with Aspire? This page covers solutions to the most common problems developers encounter.

Docker Desktop not running

Symptoms: aspire run hangs or shows “waiting for container runtime” messages.

Solution: Start Docker Desktop (or Podman) before running aspire run. Check your system tray to confirm Docker is running with a green status indicator.

Attenzione

Aspire uses containers for databases, caches, and other resources. Without a container runtime, these resources can’t start.

Port already in use

Symptoms: Error message like “Address already in use” or “Port 5000 is already bound.”

Solution:

• Stop any other applications using the same ports
• If you have another Aspire app running, stop it first with ⌃+C⌃+CControl + CCtrlCControl + CCtrlC

How to find processes using a port

Bash

lsof -i :5000
# Then kill the process:
kill -9 <pid>

PowerShell

netstat -ano | findstr :5000
# Find the PID in the last column, then:
taskkill /PID <pid> /F

Service shows “Unhealthy” in dashboard

Symptoms: A service has a red status or shows “Unhealthy” in the Aspire dashboard.

Solution:

1. Click on the service name in the dashboard to view its logs
2. Look for startup errors or exceptions
3. Verify the health check endpoint exists (e.g., /health returns a 200 OK)
4. Check that all dependencies started successfully

”Connection refused” errors

Symptoms: Your frontend can’t connect to the API, showing connection refused errors.

Solution: Make sure you’re using WaitForwaitFor in your AppHost:

AppHost.cs

builder.AddProject<Projects.WebFrontend>("frontend")
    .WithReference(apiService)
    .WaitFor(apiService);  // Add this line!

Environment variables not available

Symptoms: Your service can’t find connection strings or configuration that should be injected.

Solution: Verify you’re using WithReferencewithReference to connect resources.

Example: Connecting a database to your service

In your AppHost:

AppHost.cs

var db = builder.AddPostgres("db");
var api = builder.AddProject<Projects.Api>("api")
    .WithReference(db);  // This injects the connection string

In your service code, access the connection string via configuration:

Program.cs

var connectionString = builder.Configuration.GetConnectionString("db");

The connection string is injected as an environment variable named ConnectionStrings__db.

Container image pull failures

Symptoms: Error messages about failing to pull container images, or “image not found” errors.

Solution:

• Check your internet connection
• Verify Docker Hub or your container registry is accessible
• If using a corporate network, check proxy settings in Docker Desktop

How to manually pull and verify an image

# Try pulling the image manually
docker pull redis:latest

# If behind a proxy, configure Docker Desktop:
# Settings > Resources > Proxies > Manual proxy configuration

Dashboard not loading

Symptoms: The Aspire dashboard URL doesn’t respond or shows a blank page.

Solution:

1. Check the console output for the correct dashboard URL (it may use a different port)
2. Ensure no browser extensions are blocking the page
3. Try a different browser or incognito mode
4. Check if antivirus or firewall is blocking the connection

Service discovery not working

Symptoms: Services can’t find each other by name (e.g., http://apiservice doesn’t resolve).

Solution: Ensure you’re using the service name exactly as defined in your AppHost.

Example: Correct service discovery setup

AppHost.cs

// In AppHost
var api = builder.AddProject<Projects.Api>("apiservice");  // Name is "apiservice"

Program.cs

// In your consuming service, use exactly this name
var client = new HttpClient { BaseAddress = new Uri("http://apiservice") };

Also verify:

• Both services have AddServiceDefaults() called
• The consuming service has .WithReference(api) in the AppHost

For a deeper understanding of how service discovery works in Aspire, see Service discovery.

aspire add finds no packages with an Azure Artifacts feed

Symptoms: When an authenticated Azure DevOps or Azure Artifacts NuGet feed is configured, aspire add reports that no packages were found or the Aspire CLI logs a JsonReaderException.

Cause: The NuGet Azure Artifacts Credential Provider can write [CredentialProvider] progress text to standard output before the dotnet package search --format json response. Older Aspire CLI versions tried to parse all of that output as JSON.

Solution: Update to the latest Aspire CLI:

Update the Aspire CLI

aspire update --self

Authenticated feeds return 401

Bundled NuGet search and restore run in-process and initialize NuGet’s credential service so installed credential-provider plugins can authenticate to feeds such as Azure Artifacts.

If an authenticated feed still returns 401, check the configured feed URL, package source mapping, and credential provider installation. Authenticate using the provider’s documented workflow, and verify a restore from that same feed outside Aspire, for example with dotnet restore --interactive on a project that actually references a package from it. dotnet nuget locals only inspects or clears caches; it doesn’t verify feed authentication.

Bundled NuGet operations initialize credentials non-interactively. Complete any required interactive sign-in first rather than expecting the Aspire operation to display a credential prompt. Non-bundled search still uses dotnet package search.

TypeScript AppHost issues

”Command not found” errors

Ensure Node.js is installed and available in your PATH:

Verify Node.js installation

node --version
npm --version

CLI and SDK version mismatch

Symptoms: Commands like aspire add, aspire restore, or aspire run fail with an error similar to:

TypeScript (Node.js) SDK code generation failed because the installed Aspire CLI appears to be incompatible with the configured Aspire SDK. Run 'aspire update' to align the CLI and SDK and try again.

You may also see a warning before the failure:

The installed Aspire CLI version (X.Y.Z) differs from the Aspire SDK version (A.B.C) used for code generation. If you run into errors, update the Aspire CLI to match or exceed the SDK version.

The warning appears only when the CLI is older than the SDK. A newer CLI running an AppHost pinned to an older SDK doesn’t produce the warning, and build metadata (the part after +) is ignored. During aspire update, the warning compares the CLI against the target SDK version rather than the version currently in aspire.config.json.

Solution: Update the Aspire CLI so its version matches or exceeds the SDK version:

Update the Aspire CLI

aspire update --self

If the selected Aspire SDK is newer than the running CLI, aspire update prompts you to update the CLI first and skips the project update. Update the CLI, then run aspire update again to finish aligning the project. For standalone CLI installations, accept the prompt or run:

Update the Aspire CLI

aspire update --self

If the Aspire CLI is installed as a .NET tool, run the update command printed by the CLI before re-running aspire update.

For additional diagnostic details, re-run the failing command with the --debug flag:

Run with debug output

aspire run --debug

SDK compilation errors

If you encounter compilation errors in the generated .aspire/modules/ SDK:

1. Ensure you have the latest version of the Aspire CLI installed.
2. Delete the .aspire/modules directory and run aspire run again to regenerate the SDK.
3. Check the Aspire GitHub issues for known problems.

Debug mode

Run with debug output to diagnose issues:

Run with debug output

aspire run --log-level Debug

CLI logs

Persisted Aspire CLI logs are stored in the Aspire home directory’s logs folder. The default locations are:

Bash

$HOME/.aspire/logs/

PowerShell

$HOME\.aspire\logs\

Building from source

”Failed to copy CLI files” error on macOS or Linux

This section applies to contributors building Aspire from source with the localhive.sh script in the microsoft/aspire repository. The script installs a locally built Aspire CLI into a local hive.

Symptoms: When running localhive.sh, the script exits with:

Error output

Failed to copy CLI files from <publish_dir> to <bin_dir>

Here, <publish_dir> is the CLI dotnet publish output directory, and <bin_dir> is the CLI installation directory. By default, <bin_dir> is $HOME/.aspire/bin; if you pass -o or --output, it is the bin directory under that output path.

On macOS/BSD, this appears as cp: .../fr is a directory (not copied). On Linux/GNU, it appears as cp: -r not specified; omitting directory '...'.

Cause: The dotnet publish output for the CLI includes culture-specific resource subdirectories (for example, fr/, de/). The plain cp invocation without -R cannot copy directories.

Solution: If you’re working from the release/13.4 branch, apply the one-line copy command fix in localhive.sh:

localhive.sh

if ! cp -f "$CLI_PUBLISH_DIR"/* "$CLI_BIN_DIR"/; then
if ! cp -Rf "$CLI_PUBLISH_DIR"/. "$CLI_BIN_DIR"/; then

Alternatively, update localhive.sh from the main branch of microsoft/aspire or cherry-pick microsoft/aspire#17670 if you are pinned to a release branch.

See also

• Create your first Aspire app
• Health checks
• Service discovery