What causes "assembly must be defined when using a descriptor." in dotnet/aspnetcore?

Verify the raw marker JSON contains a non-empty 'assembly' (the DLL name without path).

assembly must be defined when using a descriptor.

Error message

assembly must be defined when using a descriptor.

What it means

Thrown by validateWebAssemblyComponentPayload (ComponentDescriptorDiscovery.ts:270) when a webassembly/auto marker lacks a truthy 'assembly' field. The assembly name identifies the .NET DLL containing the component type; without it the WebAssembly runtime cannot resolve the component.

Source

Thrown at src/Components/Web.JS/src/Services/ComponentDescriptorDiscovery.ts:270

  if (!descriptor) {
    throw new Error('descriptor must be defined when using a descriptor.');
  }

  if (sequence === undefined) {
    throw new Error('sequence must be defined when using a descriptor.');
  }

  if (!Number.isInteger(sequence)) {
    throw new Error(`Error parsing the sequence '${sequence}' for component '${JSON.stringify(payload)}'`);
  }
}

function validateWebAssemblyComponentPayload(payload: WebAssemblyMarkerData) {
  const { assembly, typeName } = payload;

  if (!assembly) {
    throw new Error('assembly must be defined when using a descriptor.');
  }

  if (!typeName) {
    throw new Error('typeName must be defined when using a descriptor.');
  }

  // Parameter definitions and values come Base64 encoded from the server, since they contain random data and can make the
  // comment invalid. We could unencode them in .NET Code, but that would be slower to do and we can leverage the fact that
  // JS provides a native function that will be much faster and that we are doing this work while we are fetching
  // blazor.boot.json
  payload.parameterDefinitions = payload.parameterDefinitions && atob(payload.parameterDefinitions);
  payload.parameterValues = payload.parameterValues && atob(payload.parameterValues);
}

function validateEndComponentPayload(json: string, prerenderId: string): void {
  const payload = JSON.parse(json) as ComponentEndMarker;
  if (Object.keys(payload).length !== 1) {
    throw new Error(`Invalid end of component comment: '${json}'`);

View on GitHub (pinned to 294cab2f9b)

Solutions

Verify the raw marker JSON contains a non-empty 'assembly' (the DLL name without path).
Use the framework's MapComponentToWebAssembly / IComponentRenderMode APIs to emit markers.
Match client and server framework versions.
Remove JSON-rewriting middleware on Blazor responses.

Defensive patterns

Strategy: validation

Validate before calling

function hasAssembly(payload: any): boolean {
  return typeof payload?.assembly === 'string' && payload.assembly.length > 0;
}

Type guard

function isWebAssemblyMarkerData(payload: any): payload is { assembly: string; typeName: string } {
  return typeof payload?.assembly === 'string' && payload.assembly.length > 0
    && typeof payload?.typeName === 'string' && payload.typeName.length > 0;
}

Prevention

Use MapComponentToWebAssembly / framework registration APIs.
Match framework versions.
Avoid rewriting marker JSON in middleware.

When it happens

Trigger: A webassembly/auto component marker whose JSON omits 'assembly'; marker emitted by code that did not set the assembly name; corrupted/transformed marker JSON.

Common situations: Custom rendering of WebAssembly root components missing the assembly name; version mismatch; middleware rewriting marker JSON; marker truncated by size limits.

Related errors

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/3b37c349c4ff4bcb. Report an issue: GitHub.