From 40c07c9de85aed6642f2c190a2e3f1252ae7394f Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 19:09:11 +0000 Subject: [PATCH 1/2] docs: document TypeScript AppHost codegen diagnostics and CLI/SDK version mismatch Documents the improved codegen failure output introduced in microsoft/aspire#17262: - CLI/SDK version skew warning before AppHost startup - Actionable error message on codegen failure (replaces bare TypeLoadException) - --debug flag for full diagnostic details - aspire update as the recommended fix Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/app-host/typescript-apphost.mdx | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index dc936b3fa..5bec5d2f4 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -511,11 +511,72 @@ aspire certs trust on HTTPS certificate management in Aspire, including Linux-specific setup. +## Troubleshooting codegen failures + +When the Aspire CLI runs a TypeScript (Node.js) AppHost, it contacts a managed server to generate the TypeScript SDK. That server loads NuGet-restored packages (`Aspire.Hosting.JavaScript`, `Aspire.TypeSystem`, and related assemblies). If the CLI version and the SDK version in `aspire.config.json` do not match on major, minor, or patch (excluding build metadata), code generation can fail. + +### CLI/SDK version mismatch warning + +Before starting the AppHost, the CLI compares its built-in version against the `Aspire.Hosting.JavaScript` version declared in `aspire.config.json`. When the two differ, the CLI prints a yellow warning: + +```text +⚠ The installed Aspire CLI version (13.4.0-preview.1.26218.1) differs from the configured + Aspire SDK version (13.4.0-preview.1.26227.1). If you run into errors, run 'aspire update' + to align them. +``` + +The AppHost still starts. If codegen succeeds despite the mismatch (for example, when the difference is only in the build number), the warning can be safely ignored. If codegen fails, run `aspire update` to realign the CLI and SDK to the same version. + +### Codegen failure output + +When code generation fails, the CLI exits immediately and prints: + +```text +❌ TypeScript (Node.js) SDK code generation failed because the installed Aspire CLI appears + to be incompatible with the configured Aspire SDK. Run 'aspire update' to align the CLI + and SDK and try again. +ℹ Run with '--debug' for full diagnostic details. +``` + + + +### Getting full diagnostic details + +Pass `--debug` to `aspire run` for detailed diagnostic output: + +```bash title="Aspire CLI" +aspire run --debug +``` + +In addition to the standard failure message, the CLI prints a diagnostic block: + +```text +🔬 Diagnostic details: +🔬 Exception: System.TypeLoadException +🔬 Type: Aspire.Hosting.SomeType +🔬 Runtime Aspire.Hosting: 13.4.0-preview.1.26218.1+abc123 +🔬 • Aspire.Hosting.CodeGeneration.TypeScript 13.4.0-preview.1.26227.1+def456 +🔬 • Aspire.TypeSystem 13.4.0-preview.1.26227.1+def456 +``` + +The same information is always written to the CLI log file at `~/.aspire/logs/cli_*.log`, even when `--debug` is not passed. + +### Resolving the mismatch + +Run `aspire update` to update the packages in `aspire.config.json` to match the installed CLI version, or reinstall the CLI to match the SDK version already in use: + +```bash title="Aspire CLI" +aspire update +``` + ## See also - [Build your first app](/get-started/first-app/?lang=typescript) - [AppHost overview](/get-started/app-host/) - [Multi-language architecture](/architecture/multi-language-architecture/) - [aspire doctor command](/reference/cli/commands/aspire-doctor/) +- [aspire update command](/reference/cli/commands/aspire-update/) - [aspire certs trust command](/reference/cli/commands/aspire-certs-trust/) - [Certificate configuration](/app-host/certificate-configuration/) From 4bfe8cf7562f3954d8227d321613dc2571628376 Mon Sep 17 00:00:00 2001 From: David Pine <7679720+IEvangelist@users.noreply.github.com> Date: Fri, 29 May 2026 20:32:48 -0500 Subject: [PATCH 2/2] Address review feedback (4 threads) - Use placeholder versions and align diagnostic output (PRRT_kwDOQK_VN86FNwD2) - Remove color-specific warning wording (PRRT_kwDOQK_VN86FNwck) - Point version-skew checks at sdk.version (PRRT_kwDOQK_VN86Ftvl9) - Include prerelease identifiers in mismatch criteria (PRRT_kwDOQK_VN86FtvmJ) Verified against microsoft/aspire@565af538808300046a1b7cbe125358661d336a4c on branch release/13.4. Edited per the doc-writer skill. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs/app-host/typescript-apphost.mdx | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx index 5bec5d2f4..4a3fb2e9e 100644 --- a/src/frontend/src/content/docs/app-host/typescript-apphost.mdx +++ b/src/frontend/src/content/docs/app-host/typescript-apphost.mdx @@ -513,19 +513,19 @@ aspire certs trust ## Troubleshooting codegen failures -When the Aspire CLI runs a TypeScript (Node.js) AppHost, it contacts a managed server to generate the TypeScript SDK. That server loads NuGet-restored packages (`Aspire.Hosting.JavaScript`, `Aspire.TypeSystem`, and related assemblies). If the CLI version and the SDK version in `aspire.config.json` do not match on major, minor, or patch (excluding build metadata), code generation can fail. +When the Aspire CLI runs a TypeScript (Node.js) AppHost, it contacts a managed server to generate the TypeScript SDK. That server loads NuGet-restored packages (`Aspire.Hosting.JavaScript`, `Aspire.TypeSystem`, and related assemblies). If the CLI version and the SDK version in `aspire.config.json` differ in major, minor, patch, or prerelease identifiers (excluding build metadata), code generation can fail. ### CLI/SDK version mismatch warning -Before starting the AppHost, the CLI compares its built-in version against the `Aspire.Hosting.JavaScript` version declared in `aspire.config.json`. When the two differ, the CLI prints a yellow warning: +Before starting the AppHost, the CLI compares its built-in SDK version against the `sdk.version` value in `aspire.config.json`. When the two differ, the CLI prints a warning: ```text -⚠ The installed Aspire CLI version (13.4.0-preview.1.26218.1) differs from the configured - Aspire SDK version (13.4.0-preview.1.26227.1). If you run into errors, run 'aspire update' +⚠ The installed Aspire CLI version () differs from the configured + Aspire SDK version (). If you run into errors, run 'aspire update' to align them. ``` -The AppHost still starts. If codegen succeeds despite the mismatch (for example, when the difference is only in the build number), the warning can be safely ignored. If codegen fails, run `aspire update` to realign the CLI and SDK to the same version. +The AppHost still starts after the warning. If codegen succeeds, no further action is required. If codegen fails, run `aspire update` to realign the CLI and SDK to the same version. ### Codegen failure output @@ -535,6 +535,8 @@ When code generation fails, the CLI exits immediately and prints: ❌ TypeScript (Node.js) SDK code generation failed because the installed Aspire CLI appears to be incompatible with the configured Aspire SDK. Run 'aspire update' to align the CLI and SDK and try again. +ℹ Run 'aspire update' to align the installed Aspire CLI with the configured SDK version, + then retry. ℹ Run with '--debug' for full diagnostic details. ``` @@ -554,11 +556,11 @@ In addition to the standard failure message, the CLI prints a diagnostic block: ```text 🔬 Diagnostic details: -🔬 Exception: System.TypeLoadException -🔬 Type: Aspire.Hosting.SomeType -🔬 Runtime Aspire.Hosting: 13.4.0-preview.1.26218.1+abc123 -🔬 • Aspire.Hosting.CodeGeneration.TypeScript 13.4.0-preview.1.26227.1+def456 -🔬 • Aspire.TypeSystem 13.4.0-preview.1.26227.1+def456 + Exception: System.TypeLoadException + Type: Aspire.Hosting.SomeType + Runtime Aspire.Hosting: + + • Aspire.Hosting.CodeGeneration.TypeScript + + • Aspire.TypeSystem + ``` The same information is always written to the CLI log file at `~/.aspire/logs/cli_*.log`, even when `--debug` is not passed.