Skip to content

troubleshooting.md

Latest commit

 

History

History
194 lines (140 loc) · 10.8 KB

troubleshooting.md

File metadata and controls

194 lines (140 loc) · 10.8 KB

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:

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

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
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), 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/