{"record":{"id":"af9fe5ce8242c108","repo":"dotnet/aspnetcore","slug":"descriptor-must-be-defined-when-using-a-descriptor","errorCode":null,"errorMessage":"descriptor must be defined when using a descriptor.","messagePattern":"descriptor must be defined when using a descriptor\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Components/Web.JS/src/Services/ComponentDescriptorDiscovery.ts","lineNumber":254,"sourceCode":"}\n\nfunction createAutoComponentComment(payload: AutoComponentMarker, start: Comment, end: Comment | undefined): AutoComponentDescriptor {\n  validateServerComponentPayload(payload);\n  validateWebAssemblyComponentPayload(payload);\n\n  return {\n    ...payload,\n    uniqueId: nextUniqueDescriptorId++,\n    start,\n    end,\n  };\n}\n\nfunction validateServerComponentPayload(payload: ServerMarkerData) {\n  const { descriptor, sequence } = payload;\n\n  if (!descriptor) {\n    throw new Error('descriptor must be defined when using a descriptor.');\n  }\n\n  if (sequence === undefined) {\n    throw new Error('sequence must be defined when using a descriptor.');\n  }\n\n  if (!Number.isInteger(sequence)) {\n    throw new Error(`Error parsing the sequence '${sequence}' for component '${JSON.stringify(payload)}'`);\n  }\n}\n\nfunction validateWebAssemblyComponentPayload(payload: WebAssemblyMarkerData) {\n  const { assembly, typeName } = payload;\n\n  if (!assembly) {\n    throw new Error('assembly must be defined when using a descriptor.');\n  }\n","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/294cab2f9b2e03af6b953820c7ab497c3c8b7ad9/src/Components/Web.JS/src/Services/ComponentDescriptorDiscovery.ts#L236-L272","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"function hasDescriptor(payload: any): boolean {\n  return typeof payload?.descriptor === 'string' && payload.descriptor.length > 0;\n}","typeGuard":"function isServerMarkerData(payload: any): payload is { descriptor: string; sequence: number; type: string } {\n  return payload && typeof payload.descriptor === 'string' && payload.descriptor.length > 0\n    && Number.isInteger(payload.sequence);\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["blazor","server-components","markers","serialization","validation"],"analyzedSha":"294cab2f9b2e03af6b953820c7ab497c3c8b7ad9","analyzedAt":"2026-08-06T20:08:02.189Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}