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.

See also

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