Setting the file. One moment.
Subchapter 33.9
references/troubleshooting.mdMarkdown11 KBView on GitHub
Aspire emits diagnostic codes for common issues. These appear in build warnings/errors and IDE 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 |
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:
<!-- In .csproj -->
<PropertyGroup>
<NoWarn>$(NoWarn);ASPIRE_HOSTINGX_0001</NoWarn>
</PropertyGroup>Or per-line:
#pragma warning disable ASPIRE_HOSTINGX_0001
var resource = builder.AddExperimentalResource("test");
#pragma warning restore ASPIRE_HOSTINGX_0001| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Problem | Solution |
|---|---|
| “cargo not found” | Install Rust via rustup |
| Build takes too long | Rust compile times are normal; use .WithCargoBuild() for pre-build |
| 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 |
| 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 |
| Traces don’t show cross-service calls | Propagate trace context headers (traceparent, tracestate) |
| 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 |
| 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 |
The dashboard shows resource state, logs, traces, and metrics. Start here for any issue.
In the dashboard, click a resource to see all injected environment variables. Verify connection strings and service URLs are correct.
Dashboard → Console Logs → filter by the failing resource. Raw stdout/stderr often contains the root cause.
If services fail to start, check the dependency order. A failed dependency blocks all downstream resources.
If MCP is configured (see MCP Server), ask your AI assistant:
Run just the failing resource by commenting out others in the AppHost. This narrows whether the issue is the resource itself or a dependency.
| Channel | URL |
|---|---|
| GitHub Issues (runtime) | https://github.com/dotnet/aspire/issues (opens in a new tab) |
| GitHub Issues (docs) | https://github.com/microsoft/aspire.dev/issues (opens in a new tab) |
| Discord | https://aka.ms/aspire/discord (opens in a new tab) |
| Stack Overflow | Tag: dotnet-aspire |
| https://www.reddit.com/r/aspiredotdev/ (opens in a new tab) |