[docs] TypeScript AppHost codegen diagnostics and CLI/SDK version mismatch

[aspire-repo-bot]

Documents changes from microsoft/aspire#17262 — @IEvangelist

Targeting release/13.4 — the latest release branch on microsoft/aspire.dev — because release/13.5 (from the source PR milestone 13.5) does not exist there.

Why this PR is needed

PR microsoft/aspire#17262 significantly improved the user-facing output when a TypeScript (Node.js) AppHost's CLI version and SDK version differ. Before the fix, users saw a bare System.TypeLoadException with no message, followed by a 60-second timeout. After the fix they see:

• A pre-flight yellow warning naming both versions and pointing at aspire update
• A clear, actionable error message on codegen failure
• A hint to pass --debug for detailed diagnostic output
• Immediate exit instead of a 60-second timeout

None of these user-visible behaviours were previously documented.

What changed

Added a Troubleshooting codegen failures section to src/frontend/src/content/docs/app-host/typescript-apphost.mdx covering:

• The CLI/SDK version mismatch warning and when it can be ignored
• The new codegen failure output format
• How to use --debug for full diagnostic details
• How aspire update resolves the mismatch

Also added aspire update to the See also list at the bottom of the page.

Files modified

• src/frontend/src/content/docs/app-host/typescript-apphost.mdx — updated (new section added)

Generated by PR Documentation Check for issue #17262 · ● 13.6M · ◷

[Copilot]

Pull request overview

Documents new TypeScript AppHost codegen diagnostics surfaced by microsoft/aspire#17262, including the CLI/SDK version mismatch warning, the new codegen failure message, the --debug diagnostic block, and pointing users to aspire update for resolution.

Changes:

• Adds a new "Troubleshooting codegen failures" section to the TypeScript AppHost docs with four subsections (mismatch warning, failure output, --debug details, and resolution).
• Adds an aspire update link to the page's "See also" list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[IEvangelist]

Docs accuracy review

Source of truth: microsoft/aspire@cc4b7eaf (release/13.4, fetched 2026-05-29)
PR head: 40c07c9de85aed6642f2c190a2e3f1252ae7394f

Verdict	Count
verified	8
verified-with-nuance	3
unverifiable	0
contradicted	1

Verdict: REQUEST_CHANGES. One factual contradiction worth fixing: the version skew check compares the CLI's built-in SDK version against the sdk.version field in aspire.config.json (AspireConfigFile.SdkVersion), not against the Aspire.Hosting.JavaScript package version. The two fields are independent — packages["Aspire.Hosting.JavaScript"] is not the value being compared. A user reading this doc and looking for Aspire.Hosting.JavaScript in their config will be looking at the wrong field.

Three smaller nuances on the example output blocks are flagged for awareness; they don't change the verdict beyond REQUEST_CHANGES.

Doc-tester (UX) notes

The new troubleshooting section gives users an actionable diagnosis for a previously-cryptic failure (empty System.TypeLoadException + 60s timeout). After the contradiction in §"CLI/SDK version mismatch warning" is fixed, the rest of the section maps reliably to terminal output. The reproduction of the warning/error text is faithful and the aspire update remediation matches the path the runtime points at.

Verified claims (with evidence)

#	Claim	Evidence
1	Yellow warning text: The installed Aspire CLI version (X) differs from the configured Aspire SDK version (Y). If you run into errors, run 'aspire update' to align them.	src/Aspire.Cli/Resources/ErrorStrings.resx:265-267 CodegenVersionSkewWarning. Emitted at src/Aspire.Cli/Projects/GuestAppHostProject.cs:1630-1635 via DisplayMessage(KnownEmojis.Warning, $"[yellow]{...}[/]", allowMarkup: true) — yellow + ⚠ confirmed.
2	"AppHost still starts" on mismatch.	GuestAppHostProject.cs:1612-1641 WarnIfCliSdkVersionSkew only emits a warning (no exception, no early return). Caller proceeds to launch.
3	Codegen failure summary: {lang} 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.	ErrorStrings.resx:269-271 CodegenIncompatibleSdkSummary. Emitted at GuestAppHostProject.cs:1686-1690 via DisplayError(summary) — ❌ prefix comes from DisplayError. The {0} slot is the AppHost DisplayName (e.g. TypeScript (Node.js)).
4	ℹ Run with '--debug' for full diagnostic details.	ErrorStrings.resx:273-275 CodegenDebugHint. Emitted at GuestAppHostProject.cs:1711-1714 via DisplayMessage(KnownEmojis.Information, $"[grey]{...}[/]", allowMarkup: true) only when !_executionContext.DebugMode.
5	🔬 Diagnostic details: header.	ErrorStrings.resx:276-277 CodegenDebugHeader = "Diagnostic details:" + KnownEmojis.Microscope (KnownEmojis.cs:46) emitted at GuestAppHostProject.cs:1717.
6	Diagnostic content fields: Exception, Type, Runtime Aspire.Hosting, per-assembly • {Name} {Version}.	GuestAppHostProject.cs:1718-1739 — DisplayPlainText($" Exception: {...}"), Type: {...}, optional Member: {...}, Runtime Aspire.Hosting: {...}, and per-assembly • {Name} {InformationalVersion} from LoadedAssemblies.
7	"The same information is always written to the CLI log file at ~/.aspire/logs/cli_*.log, even when --debug is not passed."	(a) _logger.LogDebug(...) always runs at GuestAppHostProject.cs:1698-1709 regardless of --debug. (b) src/Aspire.Cli/Program.cs:246 builder.AddFilter<FileLoggerProvider>(null, LogLevel.Debug) configures the file logger to record Debug and above. (c) FileLoggerProvider.cs:42-46 produces file names cli_{timestamp}_{id}.log in <aspire-home>/logs (default ~/.aspire/logs).
8	aspire update realigns the SDK version.	src/Aspire.Cli/Commands/UpdateCommand.cs:406 GetLatestGuestSdkVersionAsync(channel, ...) and GuestAppHostProject.cs:1427 config.SdkVersion = newSdkVersion; SaveConfiguration(config, directory).

Verified-with-nuance

#	Claim	Nuance
9	"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."	The actual check (GuestAppHostProject.cs:1658-1670 IsKnownIncompatibleSkew) is SemVersion.ComparePrecedence(cli, sdk) != 0, which covers major/minor/patch and prerelease identifiers (e.g. 13.4.0-preview.1.26218.1 vs 13.4.0-preview.1.26227.1 is flagged even though M/M/P match). The doc-level summary loses the prerelease check. The lower paragraph "for example, when the difference is only in the build number" then correctly carves out the build-metadata case.
10	Diagnostic block shows 🔬 on every line.	The microscope emoji is only on the header (GuestAppHostProject.cs:1717 DisplayMessage(KnownEmojis.Microscope, header)); the subsequent Exception: / Type: / Runtime ... / • ... lines are DisplayPlainText(...) with three-space indentation only (:1721-1738).
11	Codegen-failure block jumps directly from the ❌ summary to ℹ Run with '--debug'.	GuestAppHostProject.cs:1690-1696 emits the summary, then (if RemediationHint is non-empty) emits a grey ℹ-prefixed hint line, then (only if not in debug mode) the CodegenDebugHint line. When the diagnostic carries a RemediationHint, the user actually sees an extra ℹ line between the summary and the --debug hint.

Contradicted

#	Claim	Source-of-truth contradiction
12	"Before starting the AppHost, the CLI compares its built-in version against the Aspire.Hosting.JavaScript version declared in aspire.config.json."	The compared field is AspireConfigFile.SdkVersion (i.e. sdk.version at the top level), not packages["Aspire.Hosting.JavaScript"]. GuestAppHostProject.cs:1614-1623 WarnIfCliSdkVersionSkew reads config?.SdkVersion, which is AspireConfigFile.Sdk?.Version (AspireConfigFile.cs:84-88). A user looking for Aspire.Hosting.JavaScript in their config will be looking at the wrong field — that key lives under packages and is not read here. Suggested fix: "...the CLI compares its built-in SDK version against the sdk.version value in aspire.config.json."

[IEvangelist]

Addressed the CHANGES_REQUESTED review in 4bfe8cf. The source-backed sdk.version correction is applied, and the output examples now reflect the review notes for placeholders, the remediation hint, and diagnostic detail formatting.

[IEvangelist]

Addressed the CHANGES_REQUESTED review in 4bfe8cf. The source-backed sdk.version correction is applied, and the output examples now reflect the review notes for placeholders, the remediation hint, and diagnostic detail formatting.