dotnet/aspnetcore · 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 (ComponentDescriptorDiscovery.ts:274) when a webassembly/auto marker lacks a truthy 'typeName' field. The typeName is the full type name of the component (e.g. 'MyApp.Components.MyWidget'); without it the WebAssembly host cannot instantiate the component.

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 294cab2f9b)

Solutions

  1. Confirm the marker JSON has a non-empty 'typeName' (namespace + class).
  2. Emit markers via the framework WebAssembly component registration API.
  3. Match framework versions.
  4. Inspect served HTML to see the actual marker and fix its producer.
Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

When it happens

Trigger: A webassembly/auto marker JSON that omits 'typeName'; emitted by a custom serializer or hand-built marker; corrupted/truncated marker.

Common situations: Custom marker generation missing the type name; version mismatch; middleware dropping JSON fields; reflective component registration that failed to produce the type name.

Related errors

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