awesome-copilot/skills/aspire/references/troubleshooting.md

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/