Surface actionable diagnostic when TypeScript codegen generator is dropped by load failure

[sebastienros]

Description

When the configured Aspire SDK is out of sync with the installed CLI, running or restoring a TypeScript (Node.js) AppHost could fail with a cryptic, unactionable error:

Failed to run TypeScript (Node.js) AppHost: No code generator found for language: TypeScript. No code generators were discovered in any loaded assembly.

The root cause is a binary mismatch between the bundled apphost server and the integration assemblies on disk. The TypeScript code generator assembly (from the SDK packages) references an Aspire.TypeSystem assembly that the running apphost server cannot provide (for example, an older bundled server that predates that assembly version). During assembly discovery, CodeGeneratorResolver.DiscoverGenerators calls GetTypes(), hits a ReflectionTypeLoadException (whose loader exception is a FileNotFoundException for Aspire.TypeSystem), and silently drops the TypeScript generator. The downstream CodeGenerationService.GenerateCode then threw a plain ArgumentException, which the diagnostic builder did not classify, so the existing actionable IncompatibleAspireSdk diagnostic (with a "run aspire update" remediation hint) was never emitted. The bare exception then propagated across StreamJsonRpc to the CLI and surfaced as a raw stack trace / "unexpected error".

This change routes the swallowed load failure into that existing actionable diagnostic so the user instead sees:

Failed to run TypeScript (Node.js) AppHost: Aspire SDK code generation failed because the installed Aspire CLI appears to be incompatible with the configured SDK version. Run 'aspire update' to align the CLI and SDK and try again.

Approach

The fix is contained entirely within Aspire.Hosting.RemoteHost (the apphost server, which is bundled into the CLI). It has three parts:

• CodeGeneratorResolver now retains the ReflectionTypeLoadExceptions it swallows during discovery (via a new DiscoveryResult and GetDiscoveryLoadFailures()), instead of discarding them.
• CodeGenerationService.GenerateCode chains the first retained load failure as the inner exception of the ArgumentException it throws when no generator is found.
• CodeGenerationDiagnostic recognizes FileNotFoundException in the exception chain (in addition to the existing reflection-load cases) and builds the structured IncompatibleAspireSdk RPC error that the CLI already renders with the actionable "run aspire update" message.

Because both the affected server code and the CLI client catch path (AppHostRpcClient.InvokeCodeGenerationAsync) are shared, this applies to every command that triggers code generation (aspire run, aspire restore, etc.). No public API or codegen exports coverage changed; the CLI-side rendering path was already in place.

Verification

In addition to the unit tests, I ran a functional A/B test against a real TypeScript AppHost configured with a daily SDK, injecting the same Aspire.TypeSystem load failure. With the fix, the message flips from the cryptic "No code generator found..." to the actionable "...incompatible with the configured SDK version. Run 'aspire update'...". This was verified end-to-end via aspire run; aspire restore exercises the same shared RPC and client paths.

Fixes #18110
Fixes #17910

Checklist

• Is this feature complete?
  • Yes. Ready to ship.
  • No. Follow-up changes expected.
• Are you including unit tests for the changes and scenario tests if relevant?
  • Yes
  • No
• Did you add public API?
  • Yes
    • If yes, did you have an API Review for it?
      • Yes
      • No
    • Did you add <remarks /> and <code /> elements on your triple slash comments?
      • Yes
      • No
  • No
• Does the change make any security assumptions or guarantees?
  • Yes
    • If yes, have you done a threat model and had a security review?
      • Yes
      • No
  • No

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 18125

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 18125"

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[sebastienros]

PR #18125 - Functional Testing Report

PR: #18125 - TypeScript AppHost codegen failure -> actionable diagnostic
Head commit tested: 4aa3bcaea6
Dogfood CLI version: 13.5.0-pr.18125.g4aa3bcae (matches PR head g4aa3bcae) ✅
Platform: macOS arm64
Mode: Local (isolated install, no container)

What the PR fixes

When the installed CLI is older than the configured SDK, the bundled apphost server's
Aspire.Hosting.CodeGeneration.TypeScript references an Aspire.TypeSystem assembly the
server cannot load. CodeGeneratorResolver.DiscoverGenerators swallowed the resulting
ReflectionTypeLoadException (loader exception = FileNotFoundException for
Aspire.TypeSystem), so the TypeScript generator was silently dropped and the user got a
cryptic No code generator found for language: TypeScript instead of the existing actionable
IncompatibleAspireSdk ("run aspire update") diagnostic.

Scenario 1 - No regression on the SHIPPED PR artifact (PASS)

Installed the PR CLI to an isolated dir and ran aspire restore (issue #17910's command,
pure codegen trigger) against a minimal TypeScript AppHost (Aspire.Hosting + Aspire.Hosting.Redis).

⚙️ Restoring SDK code...
✅ SDK code restored successfully for apphost.mts.

Generated .aspire/modules/: aspire.mts (3.0 MB), base.mts, transport.mts,
.codegen-hash. Exit code 0. The TypeScript generator was discovered and ran normally -
the resolver/discovery refactor does not regress the healthy codegen path.

Note: the shipped artifact is the newest build, so its bundled server ships a matching
Aspire.TypeSystem and cannot naturally reproduce the version-mismatch failure. The
shipped server assemblies are also packed inside a single-file aspire-managed executable,
so loose-DLL injection against the artifact is not possible. The diagnostic flip is therefore
proven deterministically against the real production code (below).

Scenario 2 - Diagnostic flip proven against real production code (PASS)

The fix lives in Aspire.Hosting.RemoteHost production types
(CodeGeneratorResolver, CodeGenerationService.GenerateCode, CodeGenerationDiagnosticBuilder).
Re-ran the focused tests that drive these exact types on the current head:

Test run summary: Passed!  total: 23  failed: 0

Key deterministic proof - ServiceErrorMessageTests.GenerateCode_GeneratorDroppedByLoadFailure_ThrowsIncompatibleSdkDiagnostic:
reproduces the exact bug shape (TypeScript generator dropped because
FileNotFoundException("Aspire.TypeSystem, Version=42.42.42.42") was the loader exception)
and asserts the result is now LocalRpcException with
ErrorCode == IncompatibleAspireSdk and a non-empty RemediationHint - i.e. the cryptic
ArgumentException has flipped to the actionable update path.

Supporting coverage:

• ResolverDiagnosticsTests - resolver captures swallowed load failures via Discovery.LoadFailures.
• CodeGenerationDiagnosticBuilderTests.TryCreateRpcException_FileNotFoundLoaderException_CapturesMissingAssemblyName
  • FNFE loader exception classified + missing assembly name captured.
• FNFE over-broadening guard (addressed from review):
  • ..._StandaloneFileNotFound_PlainFilePath_IsNotClassified -> returns null (a genuine missing
    file is NOT misreported as an SDK mismatch).
  • ..._StandaloneFileNotFound_AssemblyDisplayName_IsClassified -> a standalone FNFE whose
    file name is an assembly display name (Version/PublicKeyToken) IS classified.

Verdict

• Healthy TypeScript codegen works end-to-end on the shipped PR artifact (no regression).
• The targeted failure shape now produces the actionable IncompatibleAspireSdk diagnostic
  instead of the cryptic message, with a guard preventing genuine missing-file IO errors from
  being misclassified.

PR is functionally sound for its stated intent (fixes #18110, #17910).

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[JamesNK]

LGTM. The diagnostic chain is well-structured — the heuristic to distinguish assembly-bind FileNotFoundException from plain file IO is careful, and the test coverage is thorough across all the relevant exception shapes.

[davidfowl]

When the configured Aspire SDK is out of sync with the installed CLI, running or restoring a TypeScript (Node.js) AppHost could fail with a cryptic, unactionable error:

We need to harden this, not just fix the error. I think we need a breakdown of why this is happening. Unless there was some fundamental contract breakage between the apphost server between 13.4 and 13.5 (which I am not aware of), this should not happen. The version of Aspire.Hosting should come from the apphost, the apphost server's version should not impact the ALC where integrations are loaded.

[davidfowl]

No issues with improving the error but I think there's more to fix here, this scenario should not be broken.

[github-actions]

❓ CLI E2E Tests unknown — 115 passed, 0 failed, 2 unknown (commit b01e4f0)

View all recordings

-	Test	Detail
✅	AddPackageInteractiveWhileAppHostRunningDetached	Recording · Job · CLI logs
✅	AddPackageWhileAppHostRunningDetached	Recording · Job · CLI logs
✅	AgentCommands_AllHelpOutputs_AreCorrect	Recording · Job · CLI logs
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	Recording · Job · CLI logs
✅	AgentInitCommand_MigratesDeprecatedConfig	Recording · Job · CLI logs
✅	AgentInit_NonInteractive_BundleOnlySkillsNotInCatalog	Recording · Job · CLI logs
✅	AgentMcpListResources_ExcludesResourceMarkedWithExcludeFromMcp	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost	Recording · Job · CLI logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated	Recording · Job · CLI logs
✅	AllPublishMethodsBuildDockerImages	Recording · Job · CLI logs
✅	AspireAddAndStartWorkAgainstLegacyAppHostTs	Recording · Job · CLI logs
✅	AspireAddPackageVersionToDirectoryPackagesProps	Recording · Job · CLI logs
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	Recording · Job · CLI logs
✅	AspireInit_ExistingAppHostDir_RecreatesNuGetConfigKeepsFiles	Recording · Job · CLI logs
❔	AspireInit_SolutionFile_BuildsAgainstChannelHive	Recording · Job · CLI logs
✅	AspireStartUpdatesStaleTypeScriptAppHostPath	Recording · Job · CLI logs
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	Recording · Job · CLI logs
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	Recording · Job · CLI logs
✅	Banner_DisplayedOnFirstRun	Recording · Job · CLI logs
✅	Banner_DisplayedWithExplicitFlag	Recording · Job · CLI logs
✅	Banner_NotDisplayedWithNoLogoFlag	Recording · Job · CLI logs
✅	CertificatesClean_RemovesCertificates	Recording · Job · CLI logs
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	Recording · Job · CLI logs
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	Recording · Job · CLI logs
✅	ConfigSetGet_CreatesNestedJsonFormat	Recording · Job · CLI logs
✅	CreateAndRunAspireStarterProject	Recording · Job · CLI logs
✅	CreateAndRunAspireStarterProjectWithBundle	Recording · Job · CLI logs
✅	CreateAndRunEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunJavaEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunJsReactProject	Recording · Job · CLI logs
✅	CreateAndRunPolyglotAppHostWithDevLocalhostUrls	Recording · Job · CLI logs
✅	CreateAndRunPythonReactProject	Recording · Job · CLI logs
✅	CreateAndRunTypeScriptEmptyAppHostProject	Recording · Job · CLI logs
✅	CreateAndRunTypeScriptStarterProject	Recording · Job · CLI logs
✅	CreateJavaAppHostWithViteApp	Recording · Job · CLI logs
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	Recording · Job · CLI logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces	Recording · Job · CLI logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost	Recording · Job · CLI logs
✅	DashboardRunWithOtelTracesReturnsNoTraces	Recording · Job · CLI logs
✅	DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost	Recording · Job · CLI logs
✅	DeployK8sBasicApiService	Recording · Job · CLI logs
✅	DeployK8sWithExternalHelmChart	Recording · Job · CLI logs
✅	DeployK8sWithGarnet	Recording · Job · CLI logs
✅	DeployK8sWithMongoDB	Recording · Job · CLI logs
✅	DeployK8sWithMySql	Recording · Job · CLI logs
✅	DeployK8sWithPostgres	Recording · Job · CLI logs
✅	DeployK8sWithRabbitMQ	Recording · Job · CLI logs
✅	DeployK8sWithRedis	Recording · Job · CLI logs
✅	DeployK8sWithSqlServer	Recording · Job · CLI logs
✅	DeployK8sWithValkey	Recording · Job · CLI logs
✅	DeployTypeScriptAppToKubernetes	Recording · Job · CLI logs
✅	DescribeCommandResolvesReplicaNames	Recording · Job · CLI logs
✅	DescribeCommandShowsRunningResources	Recording · Job · CLI logs
✅	DetachFormatJsonProducesValidJson	Recording · Job · CLI logs
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	Recording · Job · CLI logs
✅	DoPublishAndDeployListStepsWork	Recording · Job · CLI logs
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	Recording · Job · CLI logs
✅	DoctorCommand_DetectsDeprecatedAgentConfig	Recording · Job · CLI logs
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	Recording · Job · CLI logs
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	Recording · Job · CLI logs
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	Recording · Job · CLI logs
✅	DotNetRunFileBasedAppHostUsesAspireCliBundle	Recording · Job · CLI logs
✅	DotNetRunProjectAppHostUsesAspireCliBundle	Recording · Job · CLI logs
✅	GatewayWithoutExternalEndpoint_FailsPublishWithGuidance	Recording · Job · CLI logs
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	Recording · Job · CLI logs
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	Recording · Job · CLI logs
✅	GlobalMigration_HandlesMalformedLegacyJson	Recording · Job · CLI logs
✅	GlobalMigration_PreservesAllValueTypes	Recording · Job · CLI logs
✅	GlobalMigration_SkipsWhenNewConfigExists	Recording · Job · CLI logs
✅	GlobalSettings_MigratedFromLegacyFormat	Recording · Job · CLI logs
✅	IngressWithoutExternalEndpoint_FailsPublishWithGuidance	Recording · Job · CLI logs
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory	Recording · Job · CLI logs
✅	InteractiveCSharpInitCreatesExpectedFiles	Recording · Job · CLI logs
✅	InvalidAppHostPathWithComments_IsHealedOnRun	Recording · Job · CLI logs
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	Recording · Job · CLI logs
✅	LatestCliCanStartStableChannelAppHost	Recording · Job · CLI logs
✅	LatestCliCanStartStableChannelTypeScriptAppHost	Recording · Job · CLI logs
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	Recording · Job · CLI logs
✅	LogsCommandShowsResourceLogs	Recording · Job · CLI logs
✅	OtelLogsReturnsStructuredLogsFromStarterApp	Recording · Job · CLI logs
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	Recording · Job · CLI logs
✅	ProcessCommandCallbackReceivesCliArguments	Recording · Job · CLI logs
✅	PsCommandListsRunningAppHost	Recording · Job · CLI logs
✅	PsFormatJsonOutputsOnlyJsonToStdout	Recording · Job · CLI logs
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	Recording · Job · CLI logs
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	Recording · Job · CLI logs
✅	PublishWithDockerComposeServiceCallbackSucceeds	Recording · Job · CLI logs
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	Recording · Job · CLI logs
✅	ResourceCommand_FailedExec_ShowsLogPathAndLogHasEntries	Recording · Job · CLI logs
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	Recording · Job · CLI logs
✅	RestoreGeneratesSdkFiles	Recording · Job · CLI logs
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	Recording · Job · CLI logs
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	Recording · Job · CLI logs
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	Recording · Job · CLI logs
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	Recording · Job · CLI logs
✅	RunReportsSyntaxErrorsForDotNetAppHost	Recording · Job · CLI logs
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	Recording · Job · CLI logs
✅	SecretCrudOnDotNetAppHost	Recording · Job · CLI logs
✅	SecretCrudOnTypeScriptAppHost	Recording · Job · CLI logs
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	Recording · Job · CLI logs
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	Recording · Job · CLI logs
✅	StartReportsSyntaxErrorsForDotNetAppHost	Recording · Job · CLI logs
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	Recording · Job · CLI logs
✅	StopAllAppHostsFromAppHostDirectory	Recording · Job · CLI logs
✅	StopJavaPolyglotAppHostUsingApphostDirectory	Recording · Job · CLI logs
✅	StopNonInteractiveSingleAppHost	Recording · Job · CLI logs
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	Recording · Job · CLI logs
✅	StopWithNoRunningAppHostExitsSuccessfully	Recording · Job · CLI logs
✅	TerminalAttachFrontend_ShowsViteHelpAndDetaches	Recording · Job · CLI logs
✅	TypeScriptAppHostRunDoesNotDeadlockWhenLazyOptionsInvokeAsyncCallback	Recording · Job · CLI logs
✅	TypeScriptAppHostWithVite_AllowsDifferentGuestPkgManager	Recording · Job · CLI logs
✅	UnAwaitedChainsCompileWithAutoResolvePromises	Recording · Job · CLI logs
❔	UpdateToStable_CSharpEmptyAppHost_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_CSharpSingleFileInit_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_TypeScriptSingleFileInit_KeepsConfigChannel	Recording · Job · CLI logs
✅	UpdateToStable_TypeScript_PreviewsStablePkgsAndKeepsChannel	Recording · Job · CLI logs

---

_{📹 Recordings uploaded automatically from CI run #27423488724}

[radical]

No issues with improving the error but I think there's more to fix here, this scenario should not be broken.

Should this be draft till then?