# Aspire.Hosting.Dashboard.DashboardException: The dashboard could not be reached at 'https://localhost:17000'. Connection refused. Ensure the .NET Aspire dashboard is running.

- **ID:** `dotnet/aspire-dashboard-connection-refused`
- **Domain:** dotnet
- **Category:** network_error
- **Verification:** ai_generated
- **Fix Rate:** 90%

## Root Cause

The .NET Aspire dashboard service is not running or is not reachable at the expected address and port, usually because the dashboard was not started, the port is blocked, or the hosting process crashed.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| .NET Aspire Preview 4 (8.0.0-preview.4.24156.1) | active | — | — |
| .NET Aspire Preview 5 (8.0.0-preview.5.24201.2) | active | — | — |
| .NET Aspire Preview 6 (8.0.0-preview.6.24214.1) | active | — | — |
| .NET Aspire 8.0 GA | active | — | — |

## Workarounds

1. **Ensure the .NET Aspire dashboard is running by starting the Aspire project. In Visual Studio, press F5 or run 'dotnet run' from the project directory. Verify the dashboard URL is printed in the console output.** (95% success)
   ```
   Ensure the .NET Aspire dashboard is running by starting the Aspire project. In Visual Studio, press F5 or run 'dotnet run' from the project directory. Verify the dashboard URL is printed in the console output.
   ```
2. **Check if the dashboard port is already in use by another process. Use 'netstat -ano | findstr :17000' (Windows) or 'lsof -i :17000' (Linux/macOS). If in use, kill the conflicting process or configure a different port using the DOTNET_DASHBOARD_PORT environment variable.** (85% success)
   ```
   Check if the dashboard port is already in use by another process. Use 'netstat -ano | findstr :17000' (Windows) or 'lsof -i :17000' (Linux/macOS). If in use, kill the conflicting process or configure a different port using the DOTNET_DASHBOARD_PORT environment variable.
   ```
3. **If running in a container, ensure the dashboard container is started and port mappings are correct. Example docker-compose snippet: ports: - "17000:17000"** (80% success)
   ```
   If running in a container, ensure the dashboard container is started and port mappings are correct. Example docker-compose snippet: ports: - "17000:17000"
   ```

## Dead Ends

- **Disabling the firewall completely on the local machine.** — Overly aggressive and insecure; the issue is often that the dashboard process is not running, not a firewall block. (90% fail)
- **Changing the dashboard URL in appsettings.json to a different port without starting the dashboard on that port.** — The dashboard must be listening on the configured port; changing the URL alone does not start the service. (100% fail)
- **Restarting the IDE (Visual Studio) without restarting the Aspire project.** — Restarting the IDE does not restart the dashboard process; the project must be run again. (95% fail)