{"record":{"id":"446965f9f04c2710","repo":"nats-io/nats-server","slug":"failed-to-store-message-sequence-d-w","errorCode":null,"errorMessage":"failed to store message sequence %d: %w","messagePattern":"failed to store message sequence (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":541,"sourceCode":"\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)\n\t\t}\n\t\thdrTime := time.Unix(0, hdr.Timestamp)\n\t\tif ttl > 0 && time.Now().After(hdrTime.Add(time.Duration(ttl)*time.Second)) {\n\t\t\t// If the TTL has exceeded then there isn't much point in storing the message,\n\t\t\t// but we still need to preserve the sequence.\n\t\t\tif err := store.SkipMsgs(seq, 1); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to process expired message sequence %d: %w\", seq, err)\n\t\t\t}\n\t\t\treleaseRestoreBytes(storedSize)\n\t\t\tcontinue\n\t\t}\n\t\tif err = store.StoreRawMsg(subj, mhdr, msg, seq, hdr.Timestamp, ttl, false); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to store message sequence %d: %w\", seq, err)\n\t\t}\n\t\treleaseRestoreBytes(storedSize)\n\t}\n\n\tif !eob {\n\t\treturn mset, fmt.Errorf(\"backup was truncated\")\n\t}\n\n\t// Need to make sure that we pad out with skip msgs to preserve the last\n\t// sequence, otherwise trailing deleted messages could reuse sequence numbers.\n\tif lseq < nstate.LastSeq {\n\t\tgap := nstate.LastSeq - lseq\n\t\tif err := store.SkipMsgs(lseq+1, gap); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to process trailing gap: %w\", err)\n\t\t}\n\t}\n\treturn mset, nil\n}","sourceCodeStart":523,"sourceCodeEnd":559,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L523-L559","documentation":"RestoreStreamV2 stores each valid, non-expired message block via store.StoreRawMsg with its subject, header, payload, sequence, timestamp and TTL. This error wraps any failure from the message store, meaning the raw message could not be written to the destination stream during restore.","triggerScenarios":"store.StoreRawMsg returns an error; commonly disk full or I/O failure in the JetStream file store, a subject that violates the stream's configured subject constraints, sequence conflicts with existing stream state, or corrupted block data producing invalid subject/header bytes.","commonSituations":"Restoring a large backup onto storage without enough space, restoring into a stream whose subjects filter doesn't cover the backup's subjects, or restoring over an existing non-empty stream with conflicting sequences.","solutions":["Check server logs for the underlying StoreRawMsg error and ensure sufficient disk space","Restore into a new, empty stream (delete the partially restored stream first)","Verify the stream's subjects config covers all subjects present in the backup","Re-create the backup if block data is corrupt (checksum the archive)"],"exampleFix":"// before: restoring into existing stream with conflicting state\nnats stream restore ORDERS orders.bak\n// after: remove conflicting stream state first\nnats stream rm ORDERS && nats stream restore ORDERS orders.bak","handlingStrategy":"try-catch","validationCode":"// preflight: ensure target stream is empty and its subjects cover the backup\nfor _, s := range backupSubjects {\n    if !streamSubjectsMatch(stream.Config.Subjects, s) { return fmt.Errorf(\"stream does not cover subject %s\", s) }\n}\nif stream.State.Msgs != 0 { return fmt.Errorf(\"target stream not empty\") }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to store message sequence\") {\n    // read wrapped cause from server logs: disk full vs subject mismatch vs sequence conflict\n}","preventionTips":["Always restore into a new, empty stream","Verify stream subject filters include all backup subjects","Provision storage headroom for the full backup size","Confirm disk space before starting long restores"],"tags":["jetstream","restore","storage"],"backgroundTag":"jetstream-storage-failure","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}