dotnet/aspnetcore · error · Error

typeName must be defined when using a descriptor.

Error message

typeName must be defined when using a descriptor.

What it means

Thrown by validateWebAssemblyComponentPayload when the typeName field is missing on a webassembly component marker. Along with assembly, typeName identifies the exact component type to instantiate; without it the runtime cannot resolve the component. This is the second required field check for webassembly markers after assembly.

Solutions

1. Confirm the served comment JSON includes the fully-qualified 'typeName' (e.g. 'MyApp.Components.MyWidget').
2. Disable HTML transforms that modify Blazor comment JSON.
3. Clear output caches so stale markers are regenerated.
4. Ensure server and client Blazor versions match.

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

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

When it happens

Trigger: A webassembly component comment JSON with no 'typeName' key; the field stripped by a transform; a custom emitter that forgot the fully-qualified type name.

Common situations: HTML post-processing that drops fields; version mismatch changing the schema; hand-crafted markers; a refactor that renamed the component type but the cached/old marker is still served.

Related errors

• assembly 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/37c6caee045416e5. Report an issue: GitHub.

Appendix: source

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

  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}'`);
  }
  const prerenderEndId = payload.prerenderId;
  if (!prerenderEndId) {
    throw new Error(`End of component comment must have a value for the prerendered property: '${json}'`);

View on GitHub (pinned to 3600ca084e)