dotnet/aspnetcore · error · Error

descriptor must be defined when using a descriptor.

Error message

descriptor must be defined when using a descriptor.

What it means

Thrown by validateServerComponentPayload when the descriptor field is missing on a server component marker. Server components require a descriptor (the encrypted/signed component identifier) to map the marker to a .NET component instance. Without it the framework cannot hydrate the component.

Solutions

1. Verify the served HTML comment JSON contains a non-empty 'descriptor' field.
2. Remove any HTML post-processing that alters Blazor comment JSON.
3. Ensure the .NET prerendering pipeline is the one emitting markers (don't hand-roll them).
4. Update server and client Blazor packages to matching versions.

function assertServerMarker(payload: any) {
  if (!payload?.descriptor) {
    throw new Error('Server component marker is missing descriptor.');
  }
}

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

When it happens

Trigger: A <!--Blazor:{type:server,...}--> comment where the JSON object has no 'descriptor' key; the descriptor was stripped or renamed by a transform.

Common situations: HTML minification/serialization that drops empty or specific fields; a corrupt prerender output; a custom marker emitter that forgot the descriptor; version skew between the server emitting and client consuming the marker.

Related errors

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

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

Appendix: source

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

}

function createAutoComponentComment(payload: AutoComponentMarker, start: Comment, end: Comment | undefined): AutoComponentDescriptor {
  validateServerComponentPayload(payload);
  validateWebAssemblyComponentPayload(payload);

  return {
    ...payload,
    uniqueId: nextUniqueDescriptorId++,
    start,
    end,
  };
}

function validateServerComponentPayload(payload: ServerMarkerData) {
  const { descriptor, sequence } = payload;

  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.');
  }

View on GitHub (pinned to 3600ca084e)