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..4a3fb2e9e 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,74 @@ aspire certs trust
   on HTTPS certificate management in Aspire, including Linux-specific setup.
 </LearnMore>
 
+## 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` 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 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 (<CLI_VERSION>) differs from the configured
+   Aspire SDK version (<SDK_VERSION>). If you run into errors, run 'aspire update'
+   to align them.
+```
+
+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
+
+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 'aspire update' to align the installed Aspire CLI with the configured SDK version,
+   then retry.
+ℹ  Run with '--debug' for full diagnostic details.
+```
+
+<Aside type="tip">
+Prior to this improvement, a CLI/SDK version mismatch produced an empty `System.TypeLoadException` message followed by a 60-second timeout. If you saw that behaviour, update the CLI with `aspire update`.
+</Aside>
+
+### 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: <CLI_VERSION>+<COMMIT_SHA>
+   • Aspire.Hosting.CodeGeneration.TypeScript <SDK_VERSION>+<COMMIT_SHA>
+   • Aspire.TypeSystem <SDK_VERSION>+<COMMIT_SHA>
+```
+
+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/)