diff --git a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx index 6016fdcff9..eef51d5038 100644 --- a/src/frontend/src/content/docs/get-started/aspire-sdk.mdx +++ b/src/frontend/src/content/docs/get-started/aspire-sdk.mdx @@ -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. +::: diff --git a/src/frontend/src/content/docs/get-started/troubleshooting.mdx b/src/frontend/src/content/docs/get-started/troubleshooting.mdx index 80a203973c..d0a0c99d70 100644 --- a/src/frontend/src/content/docs/get-started/troubleshooting.mdx +++ b/src/frontend/src/content/docs/get-started/troubleshooting.mdx @@ -260,6 +260,36 @@ Persisted Aspire CLI logs are stored in the Aspire home directory's `logs` folde +## `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