microsoft/aspire · critical · DistributedApplicationException

Failed to discover the Blazor WebAssembly client project for

Error message

Failed to discover the Blazor WebAssembly client project for '{serverProjectPath}'. The ResolveWebAssemblyProjectReferences MSBuild target exited with code {result.ExitCode}.

What it means

ResolveBlazorWasmClientProjectPathAsync runs an MSBuild process targeting ResolveWebAssemblyProjectReferences on the Blazor server project to find its WASM client project. When that process exits with a non-zero code, the library logs stdout/stderr and throws a DistributedApplicationException — the client project cannot be discovered.

Solutions

Build/restore the server project manually (dotnet build/restore) to surface the underlying MSBuild error from result.StandardError in the logs.
Verify serverProjectPath points to the correct .csproj of a hosted Blazor server that references a WASM client.
Ensure the .NET SDK matching the project is installed and `dotnet msbuild` works in that directory.
Explicitly declare the WASM client relationship instead of relying on auto-discovery if your project layout is unusual.

Example fix

// before
var host = builder.AddProject<Projects.Server>("server"); // server moved/renamed
// after
var host = builder.AddProject<Projects.ServerFixed>("server"); // correct, buildable server project

Defensive patterns

Strategy: retry

Validate before calling

var exit = Process.Run("dotnet", $"msbuild {serverProjectPath} -t:ResolveWebAssemblyProjectReferences");
if (exit.ExitCode != 0) throw new InvalidOperationException($"Server project MSBuild discovery failed: {exit.StandardError}");

Try / catch

try { await ResolveBlazorWasmClientProjectPathAsync(...); } catch (DistributedApplicationException ex) when (ex.Message.Contains("exited with code")) { logger.LogError(ex, "Check logged stdout/stderr for the MSBuild failure"); throw; }

Prevention

Restore and build the server project before running the AppHost.
Keep dotnet SDK on PATH and version-compatible with the project.
Ensure the server references a WASM client project.
Validate server project paths after renames/moves.

When it happens

Trigger: Calling the hosted-Blazor/gateway setup that must auto-discover the WASM client, while the MSBuild invocation on serverProjectPath fails (bad project path, invalid csproj, missing SDK, restore errors).

Common situations: Server project path wrong or moved; project file doesn't reference a WASM client; MSBuild/dotnet not on PATH or wrong SDK; solution restore out of date; custom build props breaking the target.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/d5b3331a06d5cf4c. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Blazor/BlazorHostedExtensions.cs:238

            cancellationToken).ConfigureAwait(false);

        if (!result.Started)
        {
            var message =
                $"Failed to start '{result.Command}' while discovering the Blazor WebAssembly client project for '{serverProjectPath}'.";
            throw result.StartException is not null
                ? new DistributedApplicationException(message, result.StartException)
                : new DistributedApplicationException(message);
        }

        if (result.ExitCode != 0)
        {
            BlazorGatewayLog.WasmClientDiscoveryFailed(
                logger,
                serverProjectPath,
                result.StandardOutput,
                result.StandardError);
            throw new DistributedApplicationException(
                $"Failed to discover the Blazor WebAssembly client project for '{serverProjectPath}'. " +
                $"The ResolveWebAssemblyProjectReferences MSBuild target exited with code {result.ExitCode}.");
        }

        if (string.IsNullOrWhiteSpace(result.StandardOutput))
        {
            throw new DistributedApplicationException(
                $"The ResolveWebAssemblyProjectReferences MSBuild target returned no output for '{serverProjectPath}'.");
        }

        try
        {
            using var output = JsonDocument.Parse(result.StandardOutput);

            // MSBuild emits:
            // { "Items": { "WebAssemblyProjectReference": [{ "Identity": "/path/Client.csproj" }] } }
            if (output.RootElement.TryGetProperty("Items", out var items)
                && items.TryGetProperty("WebAssemblyProjectReference", out var projectReferences))

View on GitHub (pinned to 25830f84bd)