{"record":{"id":"f99a6bea67e1d38e","repo":"nats-io/nats-server","slug":"bad-message-header-detected","errorCode":null,"errorMessage":"bad message header detected","messagePattern":"bad message header detected","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":181,"sourceCode":"\n\t// ErrGatewayNameHasSpaces signals that the gateway name contains spaces, which is not allowed.\n\tErrGatewayNameHasSpaces = errors.New(\"gateway name cannot contain spaces\")\n\n\t// ErrNoSysAccount is returned when an attempt to publish or subscribe is made\n\t// when there is no internal system account defined.\n\tErrNoSysAccount = errors.New(\"system account not setup\")\n\n\t// ErrRevocation is returned when a credential has been revoked.\n\tErrRevocation = errors.New(\"credentials have been revoked\")\n\n\t// ErrServerNotRunning is used to signal an error that a server is not running.\n\tErrServerNotRunning = errors.New(\"server is not running\")\n\n\t// ErrServerNameHasSpaces signals that the server name contains spaces, which is not allowed.\n\tErrServerNameHasSpaces = errors.New(\"server name cannot contain spaces\")\n\n\t// ErrBadMsgHeader signals the parser detected a bad message header\n\tErrBadMsgHeader = errors.New(\"bad message header detected\")\n\n\t// ErrMsgHeadersNotSupported signals the parser detected a message header\n\t// but they are not supported on this server.\n\tErrMsgHeadersNotSupported = errors.New(\"message headers not supported\")\n\n\t// ErrNoRespondersRequiresHeaders signals that a client needs to have headers\n\t// on if they want no responders behavior.\n\tErrNoRespondersRequiresHeaders = errors.New(\"no responders requires headers support\")\n\n\t// ErrClusterNameConfigConflict signals that the options for cluster name in cluster and gateway are in conflict.\n\tErrClusterNameConfigConflict = errors.New(\"cluster name conflicts between cluster and gateway definitions\")\n\n\t// ErrClusterNameRemoteConflict signals that a remote server has a different cluster name.\n\tErrClusterNameRemoteConflict = errors.New(\"cluster name from remote server conflicts\")\n\n\t// ErrClusterNameHasSpaces signals that the cluster name contains spaces, which is not allowed.\n\tErrClusterNameHasSpaces = errors.New(\"cluster name cannot contain spaces\")\n","sourceCodeStart":163,"sourceCodeEnd":199,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L163-L199","documentation":"ErrBadMsgHeader is returned by the protocol parser when a message's header block is malformed—e.g., an invalid header line, missing HMSG/PUB-terminating structure, or a headers length that does not match the payload framing. Declared at server/errors.go:181, it signals the server (or embedded client) detected corrupt or non-conforming header data while parsing an inbound message.","triggerScenarios":"A client publishes HMSG frames with malformed header text (missing CRLF, invalid key/value encoding); a proxy or custom client corrupts the header length fields; version mismatch where an old server receives header messages it mis-parses; fuzzing or buggy SDK writing raw protocol.","commonSituations":"Hand-rolled NATS clients or middleboxes rewriting messages; tests using raw TCP sockets with malformed HMSG payloads; upgraded clients sending headers to infrastructure that mangles them.","solutions":["Fix the producing client to emit valid HMSG framing: correct header length + total length and CRLF-delimited `Key: Value` lines ending with a blank line.","Use an official NATS client's header API (nats.MsgHeader) instead of building header strings manually.","Check for proxies/middleboxes that alter message bytes and bypass them.","Upgrade old clients/servers so header support (2.2+) is consistent across the deployment."],"exampleFix":"// before: manual header bytes without CRLF\npayload := []byte(\"key:value\")\n// after\nmsg := nats.NewMsg(\"subj\")\nmsg.Header.Set(\"key\", \"value\")\nmsg.Data = body\nnc.PublishMsg(msg)","handlingStrategy":"try-catch","validationCode":"// For custom producers, validate header bytes before publishing:\n// - every line matches ^[!-9;-~]+: .*$ (printable, colon present)\n// - lines terminated with CRLF and a final blank CRLF line\n// - declared header length equals actual header byte count","typeGuard":null,"tryCatchPattern":"err := nc.PublishMsg(msg)\nif err != nil && strings.Contains(err.Error(), \"bad message header detected\") {\n    // fall back to republishing without headers and log the malformed header\n}","preventionTips":["Use official client header APIs (nats.MsgHeader) instead of hand-built header bytes.","Never run byte-rewriting proxies between clients and servers.","Pin client/server versions >= 2.2 where header support is stable.","Add raw-protocol fuzz/round-trip tests if you speak the wire protocol directly."],"tags":["nats","protocol","message-headers","parser"],"backgroundTag":"malformed-message-header","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}