# 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:

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

And run a restore:

```powershell
dotnet restore
```

### Version Mismatch

**Symptom:**

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

**Solution:**
Update all Aspire packages to match:

```xml
<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:**

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

Or change port in launchSettings.json:

```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

```powershell
# 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:

```csharp
// 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:

```csharp
// 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

```csharp
// 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:

```csharp
// 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

```powershell
# 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:

```csharp
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:

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

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

---

## ✅ Common Patterns

### Correct Resource Setup

```csharp
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:

```json
{
  "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        |

---

## 📚 Related Resources

- [Aspire Reference](../../reference/tools/aspire.md)
- [Installing the SAIF CLI](install-saif-cli.md)
- [Foundry Examples](../../foundry/index.md)