Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions src/frontend/src/content/docs/get-started/aspire-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -174,3 +174,7 @@ Set `AspireCliInvocationMode` in your AppHost `.csproj`:
:::note
`dotnet run` is noninteractive, so `dnx` restores and executes without prompting for confirmation and uses your configured NuGet sources. Restore or probe failures fail explicitly instead of falling back to an incomplete direct launch. If `dnx` can't be found on `PATH` when `Dnx` or `DnxPinned` mode is configured, the run preflight emits error `ASPIRE011` when it prepares the launch command. Install or use the .NET SDK 10.0 or later, set `AspireCliInvocationMode` to `Path` to use the global `aspire` command, or set `AspireCliPath` to an explicit Aspire CLI executable.
:::

:::caution
Only use `dotnet run` to start an AppHost in its default run mode. Launching it in publish mode — for example `dotnet run --operation publish` — starts the CLI run hook, which waits for the dashboard to become ready. Publish mode never starts the dashboard, so the command fails fast with a message to use [`aspire publish`](/reference/cli/commands/aspire-publish/) instead. See [`dotnet run --operation publish` hangs at "Starting dashboard..."](/get-started/troubleshooting/#dotnet-run---operation-publish-hangs-at-starting-dashboard) for more detail.
:::
30 changes: 30 additions & 0 deletions src/frontend/src/content/docs/get-started/troubleshooting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,36 @@ Persisted Aspire CLI logs are stored in the Aspire home directory's `logs` folde
<Code slot="windows" lang="powershell" code="$HOME\.aspire\logs\" />
</OsAwareTabs>

## `dotnet run --operation publish` hangs at "Starting dashboard..."

**Symptoms**: Running `dotnet run --operation publish` (or an equivalent
`--publisher manifest` or `AppHost:Operation` configuration override) against
an AppHost that has the [Aspire CLI run hook](/get-started/aspire-sdk/#running-with-dotnet-run)
enabled appears to hang at `Starting dashboard...` and never completes.

**Cause**: `dotnet run --operation publish` starts the AppHost in publish
mode, but the CLI run hook still waits for the dashboard to become ready
before it can hand off control. Publish mode never starts the dashboard — it
expects a publishing client to consume pipeline progress and request
shutdown — so the readiness wait never resolves.

**Solution**: Use `aspire publish` instead of `dotnet run --operation
publish` to generate deployment artifacts:

```powershell title="Use aspire publish instead"
aspire publish --project ./MyApp.AppHost/
```

Newer Aspire releases detect this mismatch and fail immediately instead of
hanging, exiting with code `2` and the following message:

```text title="Output"
An unexpected error occurred: The AppHost is in publish mode and cannot be started with 'aspire run'. Use 'aspire publish' instead.
```

See [`aspire publish`](/reference/cli/commands/aspire-publish/) for details
on generating deployment artifacts.

## Building from source

### "Failed to copy CLI files" error on macOS or Linux
Expand Down
Loading