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.

Dikkat

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 ⌃+C Control + C CtrlC Control + C CtrlC

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 WaitFor() 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 WithReference() 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.

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 configured Aspire SDK version (A.B.C). If you run into errors, run 'aspire update' to align them.

This version skew can happen when you install a newer CLI (for example, upgrading to 13.4) while your project still references an older SDK version (such as 13.3), or vice versa.

Solution: Run aspire update to align the CLI and SDK versions:

Update Aspire versions

aspire update

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

Aspire CLI logs are stored at:

Bash

$HOME/.aspire/cli/logs/

PowerShell

$HOME\.aspire\cli\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