{"record":{"id":"326861040759b3ac","repo":"nats-io/nats-server","slug":"message-sequence-d-exceeds-maximum-payload-size","errorCode":null,"errorMessage":"message sequence %d exceeds maximum payload size","messagePattern":"message sequence (.+?) exceeds maximum payload size","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":479,"sourceCode":"\t\thdr, err := tr.Next()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tseq := hdr.Sequence\n\t\tif seq == 0 {\n\t\t\t// Sentinel \"end of backup\" if all fields are zero.\n\t\t\tif hdr.Timestamp == 0 && hdr.HeaderSize == 0 && hdr.PayloadSize == 0 {\n\t\t\t\teob = true\n\t\t\t\tbreak\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"expected message sequence\")\n\t\t}\n\t\tif hdr.HeaderSize < 0 || hdr.PayloadSize < 0 || hdr.PayloadSize > math.MaxInt64-hdr.HeaderSize {\n\t\t\treturn nil, fmt.Errorf(\"invalid message lengths for sequence %d\", seq)\n\t\t}\n\t\tdeclaredSize := hdr.HeaderSize + hdr.PayloadSize\n\t\tif hdr.HeaderSize > mp || hdr.PayloadSize > mp-hdr.HeaderSize {\n\t\t\treturn nil, fmt.Errorf(\"message sequence %d exceeds maximum payload size\", seq)\n\t\t}\n\t\tif mms := int64(cfg.MaxMsgSize); mms >= 0 && (hdr.HeaderSize > mms || hdr.PayloadSize > mms-hdr.HeaderSize) {\n\t\t\treturn nil, fmt.Errorf(\"message sequence %d exceeds maximum message size\", seq)\n\t\t}\n\t\tvar storedSizeRaw uint64\n\t\tswitch cfg.Storage {\n\t\tcase MemoryStorage:\n\t\t\tstoredSizeRaw = memStoreMsgSizeRaw(len(hdr.Name), int(hdr.HeaderSize), int(hdr.PayloadSize))\n\t\tdefault:\n\t\t\tstoredSizeRaw = fileStoreMsgSizeRaw(len(hdr.Name), int(hdr.HeaderSize), int(hdr.PayloadSize))\n\t\t}\n\t\tif storedSizeRaw > math.MaxInt64 {\n\t\t\treturn nil, fmt.Errorf(\"snapshot message bytes exceed reserved restore size\")\n\t\t}\n\t\tstoredSize := int64(storedSizeRaw)\n\t\tif additional := storedSize - restoreRemaining; additional > 0 {\n\t\t\tjsa.updateUsage(tier, cfg.Storage, additional)\n\t\t\trestoreRemaining += additional","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L461-L497","documentation":"Validation guard during restore: the message's declared header+payload size exceeds the server's MaxPayload limit. This protects the restore path from oversized entries in a malicious or corrupt archive before any buffer is allocated, since restored messages must respect the same payload cap as normal publishes.","triggerScenarios":"Thrown at server/stream_backup.go:479 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Raise the server's max_payload to at least the largest message in the original stream and retry","Re-create the backup from a stream whose messages fit within the target server's payload limit","Verify the archive's header sizes are not corrupted (implausibly large declared sizes)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}