mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-21 19:05:13 +00:00
e765718787
- Move all reference docs from cli/, mcp/, framework/ subfolders into references/ per agentskills.io spec - Update all cross-references in SKILL.md and reference files - Version-gate MCP tools: 9 tools in 13.1+, docs tools (list_docs/search_docs/get_doc) in 13.2+ - Simplify integrations-catalog.md to lead with MCP tool discovery (list_integrations/get_integration_docs) - Remove .vscode/mcp.json (test artifact from aspire mcp init)
195 lines
11 KiB
Markdown
195 lines
11 KiB
Markdown
# 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/ |
|