[docs] Add TypeScript AppHost CLI/SDK version mismatch troubleshooting

[aspire-repo-bot]

Documents changes from microsoft/aspire#17556.

@aspire-repo-bot[bot] (PR authored by bot on behalf of the aspire team).

Target branch: Targeting release/13.4 based on the source PR milestone 13.4 (exact match on microsoft/aspire.dev).

Why this PR is needed

microsoft/aspire#17556 (backport of #17262 to release/13.4) enriches the TypeScript AppHost codegen error diagnostics for CLI/SDK version mismatches. Previously, commands like aspire add, aspire restore, and aspire run would fail with opaque TypeLoadException failures or timeouts when the CLI and SDK versions were incompatible (for example, running a 13.3-pinned project with a 13.4 CLI). The change adds two new actionable error messages:

• Version skew warning: "The installed Aspire CLI version (X.Y.Z) differs from the configured Aspire SDK version (A.B.C). If you run into errors, run 'aspire update' to align them."
• Incompatible SDK error: "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."
• Debug hint: "Run with '--debug' for full diagnostic details."

The existing troubleshooting page had no guidance for this scenario, leaving users without a documented resolution path.

What was changed

Updated the existing TypeScript AppHost issues section in the troubleshooting guide to add a new CLI and SDK version mismatch subsection that:

• Describes the symptoms (the new error and warning messages users will see)
• Explains the cause (version skew between CLI and SDK)
• Provides the solution (aspire update)
• Shows how to get full diagnostic details (--debug)

Files modified

• src/frontend/src/content/docs/get-started/troubleshooting.mdx — updated (new subsection added)

Generated by PR Documentation Check for issue #17556 · ● 11.6M · ◷

[Copilot]

Pull request overview

Adds troubleshooting guidance for TypeScript AppHost CLI/SDK version mismatch errors so users can recognize the new diagnostics and resolve version skew.

Changes:

• Added a “CLI and SDK version mismatch” subsection under TypeScript AppHost issues.
• Documented the error/warning text, likely cause, aspire update resolution path, and debug command example.

---

💡 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: d17fc26c79182f29b2ce3d52f5f2635569db6743

Verdict	Count
verified	4
verified-with-nuance	0
unverifiable	0
contradicted	0

Verdict: APPROVE. The codegen-failure / version-skew strings shown in the troubleshooting section reproduce the actual resource strings, and the aspire update / --debug remediation matches what the runtime points at.

Doc-tester (UX) notes

A user searching for either of the quoted strings (the codegen failure or the version-skew warning) will land here from a fresh project, and the suggested commands (aspire update, aspire run --debug) match the runtime's own remediation hint and CodegenDebugHint resource. The example commands list (aspire add, aspire restore, aspire run) is accurate — all three trigger the codegen path that can throw AppHostCodeGenerationException.

Verified claims (with evidence)

#	Claim	Evidence
1	Codegen failure 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.	src/Aspire.Cli/Resources/ErrorStrings.resx:269-271 CodegenIncompatibleSdkSummary, with {0} = AppHost language display name. Emitted at src/Aspire.Cli/Projects/GuestAppHostProject.cs:1686-1690 via DisplayError(summary).
2	Warning text: The installed Aspire CLI version (X.Y.Z) differs from the configured Aspire SDK version (A.B.C). If you run into errors, run 'aspire update' to align them.	ErrorStrings.resx:265-267 CodegenVersionSkewWarning, emitted yellow + ⚠ at GuestAppHostProject.cs:1630-1635.
3	aspire add, aspire restore, aspire run can surface this failure.	GuestAppHostProject.cs:1506-1533 (GenerateCodeViaRpcAsync) — called from the AppHost startup path that all three commands invoke when integrations are present. The catch at :1529-1533 re-throws AppHostCodeGenerationException after rendering, so the calling command exits non-zero.
4	aspire run --debug surfaces additional diagnostic details.	GuestAppHostProject.cs:1711-1739 — when _executionContext.DebugMode is true (set by --debug), the 🔬 Diagnostic details: block with Exception / Type / Member / Runtime Aspire.Hosting / per-assembly versions is printed. Otherwise only the CodegenDebugHint ("Run with '--debug'...") is shown.