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

Confirm the .NET package generating markers matches the JS bundle interpreting them.

descriptor must be defined when using a descriptor.

Error message

descriptor must be defined when using a descriptor.

What it means

Thrown by validateServerComponentPayload (ComponentDescriptorDiscovery.ts:254) when a 'server' (or 'auto') component marker's JSON lacks a truthy 'descriptor' field. The descriptor is the opaque token the .NET SideRenderer uses to identify the component instance; without it the JS side cannot bind DOM to a server component.

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

Solutions

Confirm the .NET package generating markers matches the JS bundle interpreting them.
Avoid custom/manual component marker emission; use the framework's RenderComponent API.
Inspect the raw marker JSON in the served HTML and verify 'descriptor' is present and non-empty.
Remove any middleware that rewrites JSON inside HTML comments.

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function isServerMarkerData(payload: any): payload is { descriptor: string; sequence: number; type: string } {
  return payload && typeof payload.descriptor === 'string' && payload.descriptor.length > 0
    && Number.isInteger(payload.sequence);
}

Prevention

Use framework marker generation; do not build markers by hand.
Match server and client framework versions.
Do not transform JSON inside HTML comments in middleware.

When it happens

Trigger: A server/auto marker whose payload omits 'descriptor' or sets it to empty/null; marker was hand-constructed or generated by a serializer that skipped the field; corrupted/truncated marker JSON.

Common situations: Mismatched framework versions where descriptor serialization changed; a custom endpoint that renders component markers manually without populating descriptor; HTML transformation that dropped the field from JSON inside a comment.

Related errors

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