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.

Caution

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

SDK compilation errors

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

1. Ensure you have the latest version of the Aspire CLI installed.
2. Delete the .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\

See also

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