dotnet/aspnetcore · error · Error

assembly must be defined when using a descriptor.

Error message

assembly must be defined when using a descriptor.

What it means

Thrown by validateWebAssemblyComponentPayload when the assembly field is missing on a webassembly component marker. WebAssembly components need the assembly name to locate the component type at client load time. Without it the runtime cannot resolve which DLL contains the component.

Solutions

1. Confirm the served comment JSON includes a non-empty 'assembly' field matching the DLL name.
2. Disable HTML transforms that alter Blazor comment JSON.
3. Emit markers only via the official prerendering/component-tag helper.
4. Keep server and client package versions aligned.

function assertWasmAssembly(payload: any) {
  if (!payload?.assembly) {
    throw new Error('WebAssembly component marker is missing assembly.');
  }
}

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

When it happens

Trigger: A <!--Blazor:{type:webassembly,...}--> comment with no 'assembly' key; the field stripped or renamed by an HTML transform.

Common situations: HTML minifier that drops fields; a custom marker emitter that omitted assembly; version mismatch where the marker schema changed; assembly name mismatch after a rename.

Related errors

• typeName must be defined when using a descriptor.
• descriptor must be defined when using a descriptor.
• Error parsing the sequence
• Invalid component type
• Invalid end of component comment

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

Appendix: 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 3600ca084e)