{"record":{"id":"04addfc9394414d9","repo":"nats-io/nats-server","slug":"failed-to-process-trailing-gap-w","errorCode":null,"errorMessage":"failed to process trailing gap: %w","messagePattern":"failed to process trailing gap: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":555,"sourceCode":"\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}\n","sourceCodeStart":537,"sourceCodeEnd":560,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L537-L560","documentation":"After all backup messages are stored, RestoreStreamV2 pads any trailing gap up to nstate.LastSeq with SkipMsgs so deleted trailing messages do not have their sequence numbers reused. This error wraps a failure of that final SkipMsgs call on the destination store.","triggerScenarios":"store.SkipMsgs(lseq+1, gap) fails while padding trailing sequences at the end of restore; driven by storage-layer failures (disk full, I/O error) or an inconsistent destination message store state.","commonSituations":"Restoring backups of streams with trailing deleted messages onto servers with failing or full storage, or destination streams left inconsistent by a previously failed restore attempt.","solutions":["Free disk space / fix storage errors indicated in server logs","Delete the partially restored stream and re-run the restore into a fresh stream","Verify filesystem health and restart the server so JetStream can reconcile block state","Retry the restore once the underlying SkipMsgs/storage error is resolved"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if free, err := diskFree(jsStoreDir); err != nil || free < neededBytes { return fmt.Errorf(\"insufficient JetStream storage\") }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"trailing gap\") {\n    // storage failure finalizing sequence reservation; fix storage, restore into fresh stream\n}","preventionTips":["Keep sufficient free space on JetStream volumes","Clean up failed-restore streams before retrying","Validate filesystem health periodically","Check server logs after restore attempts for storage errors"],"tags":["jetstream","restore","storage","sequences"],"backgroundTag":"jetstream-storage-failure","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}