Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
IEvangelist merged 2 commits into from
Jun 1, 2026
+63 −0
Merged

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

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
40c07c9
docs: document TypeScript AppHost codegen diagnostics and CLI/SDK ver…
aspire-repo-bot[bot] May 27, 2026
4bfe8cf
Address review feedback (4 threads)
IEvangelist May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions src/frontend/src/content/docs/app-host/typescript-apphost.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -511,11 +511,72 @@ 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` do not match on major, minor, or patch (excluding build metadata), code generation can fail.
Comment thread
IEvangelist marked this conversation as resolved.
Outdated

### 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:
Comment thread
IEvangelist marked this conversation as resolved.
Outdated
Comment thread
IEvangelist marked this conversation as resolved.
Outdated

```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.
```

<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: 13.4.0-preview.1.26218.1+abc123
🔬 • Aspire.Hosting.CodeGeneration.TypeScript 13.4.0-preview.1.26227.1+def456
Comment thread
IEvangelist marked this conversation as resolved.
Outdated
🔬 • 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/)
Loading