microsoft/aspire · error · DistributedApplicationException

Failed to parse the ResolveWebAssemblyProjectReferences…

Error message

Failed to parse the ResolveWebAssemblyProjectReferences output for '{serverProjectPath}'.

What it means

When wiring a Blazor WebAssembly client project to a hosted server project, Aspire runs the MSBuild target 'ResolveWebAssemblyProjectReferences' via dotnet msbuild and parses its JSON output to discover the client project path. This DistributedApplicationException is thrown when that output cannot be deserialized as JSON, wrapping the original JsonException. It indicates the msbuild command succeeded but produced output the parser did not understand.

Solutions

Run 'dotnet msbuild <server.csproj> -getItem:ResolveWebAssemblyProjectReferences' manually and inspect the raw output for errors/warnings before the JSON.
Verify all projects build and target a compatible .NET SDK version; run restore and rebuild.
Confirm the server project actually references a Blazor WebAssembly client project with the expected ProjectReference.
Update Aspire.Hosting.Blazor to the latest patch version in case the output-parsing contract changed upstream.

Example fix

// before
builder.AddProject<Projects.MyApp_Server>("server").WithExternalHttpEndpoints();

// after: ensure the client is a proper Blazor WASM project referenced by the server
// and that msbuild output is clean, e.g. remove custom targets that Console.WriteLine
// during ResolveWebAssemblyProjectReferences.
<PackageReference Include="Aspire.Hosting.Blazor" Version="9.*" />

Defensive patterns

Strategy: validation

Validate before calling

// Validate clean msbuild output before relying on host wiring
dotnet msbuild MyServer.csproj -getItem:ResolveWebAssemblyProjectReferences > /dev/null && echo OK

Try / catch

try { await ResolveBlazorWasmClientProjectPathAsync(...); }
catch (DistributedApplicationException ex) when (ex.InnerException is JsonException)
{ logger.LogError(ex, "ResolveWebAssemblyProjectReferences output was not valid JSON"); throw; }

Prevention

Keep project files free of targets that print to stdout during msbuild.
Keep host and client projects on the same .NET SDK version.
Run a clean restore/build before starting the AppHost.

When it happens

Trigger: Calling AddServiceDefaultsForWebAssemblyClient / ResolveBlazorWasmClientProjectPathAsync (via the EnsureEnvironment callback) when the 'dotnet msbuild -getItem:ResolveWebAssemblyProjectReferences' invocation returns non-JSON output, e.g. MSBuild warnings/errors interleaved on stdout, an SDK that changed the item shape, or a target that did not run.

Common situations: Non-standard project files with custom targets that emit console output; mismatched .NET SDK versions between host and client; a client project referenced by the server that is not actually a Blazor WASM project; environment-specific MSBuild output on CI agents.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

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

            // MSBuild emits:
            // { "Items": { "WebAssemblyProjectReference": [{ "Identity": "/path/Client.csproj" }] } }
            if (output.RootElement.TryGetProperty("Items", out var items)
                && items.TryGetProperty("WebAssemblyProjectReference", out var projectReferences))
            {
                foreach (var projectReference in projectReferences.EnumerateArray())
                {
                    if (projectReference.TryGetProperty("Identity", out var identity)
                        && identity.GetString() is { Length: > 0 } projectPath)
                    {
                        return Path.GetFullPath(projectPath, serverDirectory);
                    }
                }
            }
        }
        catch (JsonException ex)
        {
            throw new DistributedApplicationException(
                $"Failed to parse the ResolveWebAssemblyProjectReferences output for '{serverProjectPath}'.",
                ex);
        }

        return null;
    }

    private static void AddBrowserDebuggerResource(
        IResourceBuilder<ProjectResource> host,
        string serverProjectPath,
        Func<string?> clientProjectPathProvider,
        string? relativePath,
        string browser)
    {
        var workingDirectory = Path.GetDirectoryName(serverProjectPath) ?? serverProjectPath;

        BrowserDebuggerHelper.AddBrowserDebuggerResource(
            host.ApplicationBuilder,

View on GitHub (pinned to 25830f84bd)