{"record":{"id":"6da37097cbd1999f","repo":"nats-io/nats-server","slug":"message-sequence-d-exceeds-maximum-message-size","errorCode":null,"errorMessage":"message sequence %d exceeds maximum message size","messagePattern":"message sequence (.+?) exceeds maximum message size","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":482,"sourceCode":"\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\n\t\t\tif err := checkUsageLimits(); err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L464-L500","documentation":"Validation guard during restore: the message's declared header+payload size exceeds the target stream's MaxMsgSize limit (when configured). The archive contains a message larger than the stream policy allows, so the restore is rejected rather than silently violating the stream's per-message size cap.","triggerScenarios":"Thrown at server/stream_backup.go:482 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Increase the stream's max_msg_size (and the server's max_payload) to accommodate the archived messages before restoring","Restore into a stream whose limits match or exceed those of the source stream","Confirm the archived header sizes are accurate and not corrupted"],"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-08T10:18:20.063Z"}