Skip to content

[docs] Add troubleshooting section for language support load failures in aspire new #1024

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

Open
aspire-repo-bot wants to merge 1 commit into
base: release/13.4
Choose a base branch
from
+38 −0
Open

[docs] Add troubleshooting section for language support load failures in aspire new #1024

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 38 additions & 0 deletions src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,3 +178,41 @@ The `aspire-py-starter` template accepts the following additional options:
```bash title="Aspire CLI"
aspire new aspire-starter --channel daily
```

## Troubleshooting

### Language support not found

When `aspire new` runs a template that requires code generation (for example, a TypeScript or Python AppHost template), it uses language support and code generator assemblies loaded by the apphost server. If those assemblies cannot load their types, the command may fail with an error such as:

```
No language support found for: typescript/nodejs. Available languages: go, java, python, rust.
```

Or, when no language support implementations are discovered at all:

```
No language support found for: typescript/nodejs. No language support implementations were discovered in any loaded assembly.
This usually indicates a binary mismatch between the bundled apphost server and the integration assemblies on disk;
check the apphost server log for 'LoaderExceptions' Warnings.
Comment on lines +196 to +197
```

These errors mean the integration assemblies on disk are not compatible with the bundled apphost server. This typically happens after a partial NuGet cache update, a version skew between the CLI and the integration packages, or an interrupted restore.

**To resolve:**

1. Clear the Aspire CLI cache to remove stale cached assemblies:

```bash title="Aspire CLI"
aspire cache clear
```

2. Re-run `aspire new` to trigger a fresh restore of the integration packages.

If the error persists, check the apphost server log for `Warning` entries that include `LoaderExceptions` or mention a shared assembly version mismatch (for example, `Aspire.TypeSystem` bundled version vs. the version on disk). These log entries name the offending assembly and describe the mismatch, making it easier to identify which package version is out of sync.

<Aside type="tip">
Run `aspire new` with `--log-level Debug` (or `--log-level Trace`) to write a
detailed log file. Open the log and search for `LoaderExceptions` or
`version mismatch` to identify the conflicting assembly.
</Aside>
Loading