{"record":{"id":"4c3b54fe68806e78","repo":"dotnet/aspnetcore","slug":"invalid-headers","errorCode":null,"errorMessage":"Invalid headers.","messagePattern":"Invalid headers\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/SignalR/clients/ts/signalr-protocol-msgpack/src/MessagePackHubProtocol.ts","lineNumber":368,"sourceCode":"        return BinaryMessageFormat.write(payload.slice());\n    }\n\n    private _writeAck(ackMessage: AckMessage): ArrayBuffer {\n        const payload = this._encoder.encode([MessageType.Ack, ackMessage.sequenceId]);\n\n        return BinaryMessageFormat.write(payload.slice());\n    }\n\n    private _writeSequence(sequenceMessage: SequenceMessage): ArrayBuffer {\n        const payload = this._encoder.encode([MessageType.Sequence, sequenceMessage.sequenceId]);\n\n        return BinaryMessageFormat.write(payload.slice());\n    }\n\n    private _readHeaders(properties: any): MessageHeaders {\n        const headers: MessageHeaders = properties[1] as MessageHeaders;\n        if (typeof headers !== \"object\") {\n            throw new Error(\"Invalid headers.\");\n        }\n        return headers;\n    }\n}\n","sourceCodeStart":350,"sourceCodeEnd":373,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/SignalR/clients/ts/signalr-protocol-msgpack/src/MessagePackHubProtocol.ts#L350-L373","documentation":"Thrown by the MessagePack protocol decoder when reading headers from an incoming message's properties array. The headers are expected at index [1] of the decoded properties and must be a plain object. If that slot is anything other than an object (e.g. undefined, a number, a string, or an array), the client cannot associate headers with the message and refuses to process it.","triggerScenarios":"Invoked from _readHeaders(properties) when a MessagePack-encoded HubMessage is parsed and properties[1] fails the typeof === \"object\" check. Happens when a client/server version mismatch alters the encoded properties layout, when a custom MessagePack encoder omits the headers map, or when a non-SignalR endpoint returns bytes that get fed into the MessagePack protocol parser.","commonSituations":"Server and client are running incompatible MessagePack protocol versions (e.g. ASP.NET Core SignalR 1.x vs 3.x changed the properties layout). A proxy or middleware rewrote or truncated the binary frame. Connecting a MessagePack client to a server that only speaks JSON.","solutions":["Align client and server @microsoft/signalr-protocol-msgpack versions to the same major release as the server package.","Verify the endpoint URL actually points to a SignalR MessagePack hub, not a JSON hub or unrelated service.","Inspect the raw bytes being delivered to parseMessages to confirm the properties array shape matches the documented MessagePack framing.","If interoperating with a non-.NET server, ensure the encoder produces the exact properties layout: [headers, ...] where headers is a Map/object."],"exampleFix":"// before: mismatched protocol packages\n// server: Microsoft.AspNetCore.SignalR.Common 3.1\n// client: @microsoft/signalr-protocol-msgpack 5.0\n\n// after: aligned versions\n// server: Microsoft.AspNetCore.SignalR.Common 5.0\n// client: @microsoft/signalr-protocol-msgpack 5.0","handlingStrategy":"validation","validationCode":"// Validate that your MessagePack encoder produces an object at properties[1]\nfunction assertValidHeaders(properties: unknown): asserts properties is [unknown, Record<string, unknown>] {\n  if (!Array.isArray(properties) || typeof properties[1] !== \"object\" || properties[1] === null) {\n    throw new Error(\"Refusing to send: MessagePack headers are malformed.\");\n  }\n}","typeGuard":"function isMessageHeaders(v: unknown): v is Record<string, string> {\n  return typeof v === \"object\" && v !== null && !Array.isArray(v);\n}","tryCatchPattern":"try {\n  await connection.start();\n} catch (e) {\n  if (e instanceof Error && e.message === \"Invalid headers.\") {\n    // almost always a client/server protocol version mismatch\n    console.error(\"MessagePack protocol mismatch — align @microsoft/signalr-protocol-msgpack with the server version.\");\n  }\n  throw e;\n}","preventionTips":["Pin @microsoft/signalr and @microsoft/signalr-protocol-msgpack to the same version as the server's Microsoft.AspNetCore.SignalR package.","Do not feed non-SignalR bytes into a MessagePack HubConnection.","If you write a custom MessagePack encoder, validate the properties layout in tests."],"tags":["messagepack","protocol","version-mismatch","serialization"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}