{"record":{"id":"c31c4e6712784262","repo":"nats-io/nats-server","slug":"failed-to-read-message-sequence-d-unexpected-pay","errorCode":null,"errorMessage":"failed to read message sequence %d: unexpected payload size","messagePattern":"failed to read message sequence (.+?): unexpected payload size","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":510,"sourceCode":"\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}\n\t\t}\n\t\tbuf, err := io.ReadAll(tr)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to read message sequence %d: %w\", seq, err)\n\t\t}\n\t\tif hdr.HeaderSize > int64(len(buf)) {\n\t\t\treturn nil, fmt.Errorf(\"failed to parse message sequence %d: invalid header length\", seq)\n\t\t}\n\t\tif int64(len(buf)) != declaredSize {\n\t\t\treturn nil, fmt.Errorf(\"failed to read message sequence %d: unexpected payload size\", seq)\n\t\t}\n\t\tsubj := hdr.Name\n\t\tmhdr := buf[:hdr.HeaderSize]\n\t\tmsg := buf[hdr.HeaderSize : hdr.HeaderSize+hdr.PayloadSize]\n\t\tif seq <= lseq {\n\t\t\treturn nil, fmt.Errorf(\"message sequence %d out of order\", seq)\n\t\t}\n\t\t// We could have deleted messages since the last message we stored, if so\n\t\t// we should work out what the gap is and skip those sequences.\n\t\tif gap := seq - lseq - 1; gap > 0 {\n\t\t\tif err := store.SkipMsgs(lseq+1, gap); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to process gap: %w\", err)\n\t\t\t}\n\t\t}\n\t\tlseq = seq\n\t\tttl, err := getMessageTTL(mhdr)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to parse message TTL: %w\", err)","sourceCodeStart":492,"sourceCodeEnd":528,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L492-L528","documentation":"During RestoreStreamV2, each message block read from the backup has a declared size (declaredSize from the header record). After reading the block, the total bytes read must equal that declared size. This error means the actual payload length differs from the declared size, so the backup data is inconsistent or truncated.","triggerScenarios":"io.ReadAll(tr) returned a buffer whose length (len(buf)) does not equal the size declared in the block header for that sequence; occurs when the block stream is truncated, records were misaligned by earlier corruption, or the backup was produced/modified incorrectly.","commonSituations":"Restoring a partially downloaded backup, a backup whose file offsets shifted due to manual edits or merge attempts, or restoring a file written by a newer/older server version with a different block layout.","solutions":["Re-create the backup and verify file size/checksums before restoring","Ensure the full backup file was transferred (compare byte counts between source and destination)","Do not manually edit or concatenate backup files; restore from the original archive","Use a compatible nats-server version for both backup (StreamBackup/backup API) and restore"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if wantSize > 0 && gotSize != wantSize { return fmt.Errorf(\"backup size mismatch: got %d want %d\", gotSize, wantSize) }","typeGuard":null,"tryCatchPattern":"if err := restore(...); err != nil && strings.Contains(err.Error(), \"unexpected payload size\") {\n    // abort and re-fetch a fresh backup\n}","preventionTips":["Compare source and destination file sizes after transfer","Restore only from completed, checksummed backups","Avoid pipes/proxies that can alter byte streams","Pin nats-server version across backup/restore"],"tags":["jetstream","restore","corruption","backup"],"backgroundTag":"corrupt-backup-file","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}