From 68bb43299f70355663991d627da678ba18d9fbc2 Mon Sep 17 00:00:00 2001 From: "aspire-repo-bot[bot]" <268009190+aspire-repo-bot[bot]@users.noreply.github.com> Date: Wed, 20 May 2026 18:33:26 +0000 Subject: [PATCH] docs: add troubleshooting section for language support load failures in aspire new Documents the improved diagnostics surfaced in microsoft/aspire#17311: - New error messages that list available languages when a specific language is not found - The binary-mismatch error message and guidance when no language support implementations are discovered at all - Resolution steps (aspire cache clear, checking the log for LoaderExceptions and version mismatch warnings) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../reference/cli/commands/aspire-new.mdx | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx index 4e015290d..783d70f6b 100644 --- a/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx +++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx @@ -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. +``` + +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. + +