Skip to content

github/awesome-copilot / skills/aspire

aspire

Flagged

Aspire skill covering the Aspire CLI, AppHost orchestration, service discovery, integrations, MCP server, VS Code extension, Dev Containers, GitHub Codespaces, templates, dashboard, and deployment. Use when the user asks to create, run, debug, configure, deploy, or troubleshoot an Aspire distributed application.

references/troubleshooting.md

View on GitHub
# Troubleshooting — Diagnostics & Common Issues

---

## Diagnostic Codes

Aspire emits diagnostic codes for common issues. These appear in build warnings/errors and IDE diagnostics.

### Standard diagnostics

| Code          | Severity | Description                                                |
| ------------- | -------- | ---------------------------------------------------------- |
| **ASPIRE001** | Warning  | Resource name contains invalid characters                  |
| **ASPIRE002** | Warning  | Duplicate resource name detected                           |
| **ASPIRE003** | Error    | Missing required package reference                         |
| **ASPIRE004** | Warning  | Deprecated API usage                                       |
| **ASPIRE005** | Error    | Invalid endpoint configuration                             |
| **ASPIRE006** | Warning  | Health check not configured for resource with `.WaitFor()` |
| **ASPIRE007** | Warning  | Container image tag not specified (using `latest`)         |
| **ASPIRE008** | Error    | Circular dependency detected in resource graph             |

### Experimental diagnostics (ASPIREHOSTINGX\*)

These codes indicate usage of experimental/preview APIs. They may require `#pragma warning disable` or `<NoWarn>` if you intentionally use experimental features:

| Code                      | Area                             |
| ------------------------- | -------------------------------- |
| ASPIRE_HOSTINGX_0001–0005 | Experimental hosting APIs        |
| ASPIRE_HOSTINGX_0006–0010 | Experimental integration APIs    |
| ASPIRE_HOSTINGX_0011–0015 | Experimental deployment APIs     |
| ASPIRE_HOSTINGX_0016–0022 | Experimental resource model APIs |

To suppress experimental warnings:

```xml
<!-- In .csproj -->
<PropertyGroup>
  <NoWarn>$(NoWarn);ASPIRE_HOSTINGX_0001</NoWarn>
</PropertyGroup>
```

Or per-line:

```csharp
#pragma warning disable ASPIRE_HOSTINGX_0001
var resource = builder.AddExperimentalResource("test");
#pragma warning restore ASPIRE_HOSTINGX_0001
```

---

## Common Issues & Solutions

### Container runtime

| Problem                           | Solution                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ |
| "Cannot connect to Docker daemon" | Start Docker Desktop / Podman / Rancher Desktop                                                        |
| Container fails to start          | Check `docker ps -a` for exit codes; check dashboard console logs                                      |
| Port already in use               | Another process is using the port; Aspire auto-assigns, but `targetPort` must be free on the container |
| Container image pull fails        | Check network connectivity; verify image name and tag                                                  |
| "Permission denied" on Linux      | Add user to `docker` group: `sudo usermod -aG docker $USER`                                            |

### Service discovery

| Problem                       | Solution                                                                     |
| ----------------------------- | ---------------------------------------------------------------------------- |
| Service can't find dependency | Verify `.WithReference()` in AppHost; check env vars in dashboard            |
| Connection string is null     | The reference resource name doesn't match; check `ConnectionStrings__<name>` |
| Wrong port in service URL     | Check `targetPort` vs actual service listen port                             |
| Env var not set               | Rebuild AppHost; verify resource name matches exactly                        |

### Python workloads

| Problem                           | Solution                                                        |
| --------------------------------- | --------------------------------------------------------------- |
| "Python not found"                | Ensure Python is on PATH; specify full path in `AddPythonApp()` |
| venv not found                    | Use `.WithVirtualEnvironment()` or create venv manually         |
| pip packages fail to install      | Use `.WithPipPackages()` or install in venv before `aspire run` |
| ModuleNotFoundError               | venv isn't activated; `.WithVirtualEnvironment()` handles this  |
| "Port already in use" for Uvicorn | Check `targetPort` — another instance may be running            |

### JavaScript / TypeScript workloads

| Problem                       | Solution                                                         |
| ----------------------------- | ---------------------------------------------------------------- |
| "node_modules not found"      | Use `.WithNpmPackageInstallation()` to auto-install              |
| npm install fails             | Check `package.json` is valid; check npm registry connectivity   |
| Vite dev server won't start   | Verify `vite` is in devDependencies; check Vite config           |
| Port mismatch                 | Ensure `targetPort` matches the port in your JS framework config |
| TypeScript compilation errors | These happen in the service, not Aspire — check service logs     |

### Go workloads

| Problem                    | Solution                                                   |
| -------------------------- | ---------------------------------------------------------- |
| "go not found"             | Ensure Go is installed and on PATH                         |
| Build fails                | Check `go.mod` exists in working directory                 |
| "no Go files in directory" | Verify `workingDir` points to the directory with `main.go` |

### Java workloads

| Problem                  | Solution                                                |
| ------------------------ | ------------------------------------------------------- |
| "java not found"         | Ensure JDK is installed and `JAVA_HOME` is set          |
| Maven/Gradle build fails | Verify build files exist; check build tool installation |
| Spring Boot won't start  | Check `application.properties`; verify main class       |

### Rust workloads

| Problem              | Solution                                                             |
| -------------------- | -------------------------------------------------------------------- |
| "cargo not found"    | Install Rust via rustup                                              |
| Build takes too long | Rust compile times are normal; use `.WithCargoBuild()` for pre-build |

### Health checks & startup

| Problem                      | Solution                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------ |
| Resource stuck in "Starting" | Health check endpoint not responding; check service logs                       |
| `.WaitFor()` timeout         | Increase timeout or fix health endpoint; default is 30 seconds                 |
| Health check always fails    | Verify endpoint path (default: `/health`); check service binds to correct port |
| Cascading startup failures   | A dependency failed; check the root resource first                             |

### Dashboard

| Problem                               | Solution                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------- |
| Dashboard doesn't open                | Check terminal for URL; use `--dashboard-port` for fixed port             |
| No logs appearing                     | Service may not be writing to stdout/stderr; check console output         |
| No traces for non-.NET services       | Configure OpenTelemetry SDK in the service; see [Dashboard](dashboard.md) |
| Traces don't show cross-service calls | Propagate trace context headers (`traceparent`, `tracestate`)             |

### Build & configuration

| Problem                                   | Solution                                                            |
| ----------------------------------------- | ------------------------------------------------------------------- |
| "Project not found" for `AddProject<T>()` | Ensure `.csproj` is in the solution and referenced by AppHost       |
| Package version conflicts                 | Pin all Aspire packages to the same version                         |
| AppHost won't build                       | Check `Aspire.AppHost.Sdk` is in the project; run `dotnet restore`  |
| `aspire run` build error                  | Fix the build error first; `aspire run` requires a successful build |

### Deployment

| Problem                                  | Solution                                                             |
| ---------------------------------------- | -------------------------------------------------------------------- |
| `aspire publish` fails                   | Check publisher package is installed (e.g., `Aspire.Hosting.Docker`) |
| Generated Bicep has errors               | Check for unsupported resource configurations                        |
| Container image push fails               | Verify registry credentials and permissions                          |
| Missing connection strings in deployment | Check generated ConfigMaps/Secrets match resource names              |

---

## Debugging strategies

### 1. Check the dashboard first

The dashboard shows resource state, logs, traces, and metrics. Start here for any issue.

### 2. Check environment variables

In the dashboard, click a resource to see all injected environment variables. Verify connection strings and service URLs are correct.

### 3. Read console logs

Dashboard → Console Logs → filter by the failing resource. Raw stdout/stderr often contains the root cause.

### 4. Check the DAG

If services fail to start, check the dependency order. A failed dependency blocks all downstream resources.

### 5. Use MCP for AI-assisted debugging

If MCP is configured (see [MCP Server](mcp-server.md)), ask your AI assistant:

- "What resources are failing?"
- "Show me the logs for [service]"
- "What traces show errors?"

### 6. Isolate the problem

Run just the failing resource by commenting out others in the AppHost. This narrows whether the issue is the resource itself or a dependency.

---

## Getting help

| Channel                 | URL                                            |
| ----------------------- | ---------------------------------------------- |
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues        |
| GitHub Issues (docs)    | https://github.com/microsoft/aspire.dev/issues |
| Discord                 | https://aka.ms/aspire/discord                  |
| Stack Overflow          | Tag: `dotnet-aspire`                           |
| Reddit                  | https://www.reddit.com/r/aspiredotdev/         |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall