Skip to content

Aspire Troubleshooting

Common Aspire issues and solutions for Forge projects.

📋 Overview

This guide covers common issues you may encounter when working with Aspire in Forge projects and how to resolve them.

🚀 Startup Issues

SDK Not Found

Symptom:

error MSB4236: The SDK 'Aspire.AppHost.Sdk/13.1.0' specified could not be found.

Solution: Ensure your AppHost project uses the correct SDK format:

<Project Sdk="Aspire.AppHost.Sdk/13.1.0">

And run a restore:

dotnet restore

Version Mismatch

Symptom:

error: Aspire.Hosting.AppHost version X does not match SDK version Y

Solution: Update all Aspire packages to match:

<ItemGroup>
  <PackageReference Include="Aspire.Hosting" Version="13.1.0" />
  <PackageReference Include="Aspire.Hosting.AppHost" Version="13.1.0" />
</ItemGroup>

Port Already in Use

Symptom:

System.Net.Sockets.SocketException: Address already in use

Solution:

# Find and kill process
Get-NetTCPConnection -LocalPort 5000 |
    Select-Object -ExpandProperty OwningProcess |
    ForEach-Object { Stop-Process -Id $_ -Force }

Or change port in launchSettings.json:

{
  "profiles": {
    "http": {
      "applicationUrl": "http://localhost:5001"
    }
  }
}

📦 Resource Issues

Container Won't Start

Symptom: Container resource stays in "Starting" state

Checks:

  1. Docker is running
  2. Image exists or can be pulled
  3. Port isn't in use
  4. Sufficient resources
# Verify Docker
docker info

# Pull image manually
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator

# Check container logs
docker logs <container-name>

Database Connection Failed

Symptom:

Unable to connect to database resource

Solution: Ensure connection string uses Aspire's service discovery:

// Correct - uses Aspire reference
builder.AddProject<Projects.MyApi>("api")
    .WithReference(database);

// In API - gets connection from configuration
var conn = builder.Configuration.GetConnectionString("database");

Resource Reference Not Found

Symptom:

error CS0103: The name 'database' does not exist in the current context

Solution: Ensure resource is created before reference:

// Create resource first
var database = builder.AddSqlServer("sql")
    .AddDatabase("mydb");

// Then reference it
builder.AddProject<Projects.MyApi>("api")
    .WithReference(database);

🔍 Service Discovery Issues

Service Not Found

Symptom:

HttpRequestException: No such host is known

Checks:

  1. Resource name matches reference name
  2. Resource is actually running
  3. Using correct endpoint name
// Correct naming
var api = builder.AddProject<Projects.MyApi>("my-api");

// Consuming service references by name
builder.AddProject<Projects.MyFrontend>("frontend")
    .WithReference(api);

Endpoint Not Available

Symptom: Service is running but can't be reached

Solution: Check endpoint configuration:

// Expose endpoint explicitly
builder.AddProject<Projects.MyApi>("api")
    .WithHttpsEndpoint(port: 5001, name: "https");

🖥️ Dashboard Issues

Dashboard Won't Open

Symptom: Browser shows error or blank page

Checks:

  1. Aspire is fully started
  2. Dashboard URL is correct (usually https://localhost:15888)
  3. No browser extensions blocking
# Get dashboard URL from output
aspire run

# Look for:
# Dashboard: https://localhost:15888

Dashboard Shows No Resources

Symptom: Dashboard loads but resources list is empty

Checks:

  1. AppHost is running (not just API)
  2. Resources are registered in Program.cs
  3. Check for startup errors

🧪 Integration Test Issues

Tests Can't Find Services

Symptom:

Service not available: https://api/

Solution: Use Aspire test fixtures:

public class IntegrationTests : IClassFixture<AspireAppFixture>
{
    private readonly AspireAppFixture _fixture;

    public IntegrationTests(AspireAppFixture fixture)
    {
        _fixture = fixture;
    }

    [Fact]
    public async Task Test()
    {
        var client = _fixture.CreateClient("api");
        // ...
    }
}

Resource Not Ready in Time

Symptom: Tests fail with connection errors intermittently

Solution: Add health check waits:

builder.AddProject<Projects.MyApi>("api")
    .WithHealthCheck("api-health");

// In test
await _fixture.WaitForResourceAsync("api", TimeSpan.FromSeconds(30));

✅ Common Patterns

Correct Resource Setup

var builder = DistributedApplication.CreateBuilder(args);

// Infrastructure resources
var sql = builder.AddSqlServer("sql")
    .AddDatabase("mydb");

var cosmos = builder.AddAzureCosmosDB("cosmos")
    .AddDatabase("data");

// Application with references
var api = builder.AddProject<Projects.MyApi>("api")
    .WithReference(sql)
    .WithReference(cosmos);

var frontend = builder.AddProject<Projects.MyFrontend>("frontend")
    .WithReference(api);

builder.Build().Run();

Debug Logging

Enable detailed Aspire logging:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Aspire": "Debug"
    }
  }
}

⚡ Quick Fixes

Issue Quick Fix
Port in use Change port or kill process
Container stuck Restart Docker
Package mismatch Update all to same version
Service not found Check resource name spelling
Dashboard blank Clear browser cache
Tests timeout Increase wait timeout