{"record":{"id":"0a9f786ef6208cf4","repo":"nats-io/nats-server","slug":"error-purging-stream-w","errorCode":null,"errorMessage":"error purging stream: %w","messagePattern":"error purging stream: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":391,"sourceCode":"\t}\n\tdefer func() {\n\t\tvar state StreamState\n\t\tmset.store.FastState(&state)\n\t\tmset.mu.Lock()\n\t\tmset.lseq = state.LastSeq\n\t\tmset.mu.Unlock()\n\t\tif err := mset.completeRestore(); err != nil {\n\t\t\tif err = fmt.Errorf(\"failed to activate stream %q: %w\", cfg.Name, err); retErr == nil {\n\t\t\t\tretErr = err\n\t\t\t}\n\t\t\ts.Warnf(\"JetStream stream restore for '%s > %s' failed to activate stream: %v\", a.Name, cfg.Name, err)\n\t\t}\n\t}()\n\n\t// Start off at the right sequence number. This is important in particular\n\t// when the backup contains no messages or would restore to no interest.\n\tif _, err = mset.store.Compact(nstate.FirstSeq); err != nil {\n\t\treturn nil, fmt.Errorf(\"error purging stream: %w\", err)\n\t}\n\n\tvar restoredConsumers, ephemerals []*consumer\n\tdefer func() {\n\t\t// Consumers must be unconditionally converted and completed, otherwise\n\t\t// a partial restore that fails midway through can leave assets that are\n\t\t// unusable.\n\t\tfor _, o := range ephemerals {\n\t\t\to.switchToEphemeral()\n\t\t}\n\t\tfor _, o := range restoredConsumers {\n\t\t\tif err := o.completeRestore(); err != nil {\n\t\t\t\tif err = fmt.Errorf(\"failed to activate consumer %q: %w\", o.name, err); retErr == nil {\n\t\t\t\t\tretErr = err\n\t\t\t\t}\n\t\t\t\ts.Warnf(\"JetStream stream restore for '%s > %s' failed to activate consumers: %v\", a.Name, cfg.Name, err)\n\t\t\t}\n\t\t}","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L373-L409","documentation":"After the stream is created in restore mode, the store is compacted to nstate.FirstSeq so the restored messages start at the correct sequence (essential when the backup is empty or restores to no interest). If store.Compact fails, the restore aborts with this wrapped storage error.","triggerScenarios":"mset.store.Compact(nstate.FirstSeq) returns an error: the storage engine (file/memory) fails to truncate the stream to the snapshot's FirstSeq — usually disk I/O errors, out-of-space conditions, or a corrupted freshly-created store; a malformed snapshot with an invalid FirstSeq can also drive edge-case store behavior.","commonSituations":"Filesystem full or read-only during a restore to a FileStorage stream; restoring onto a volume with failing disks; snapshot state.json with FirstSeq values inconsistent with the target store; very large Compact operations hitting memory limits in MemoryStorage.","solutions":["Check the store's underlying cause in logs: free disk space, fix permissions, or replace failing storage","Verify state.json's FirstSeq is a sane value from the original backup; regenerate the snapshot if it was hand-edited","For MemoryStorage streams, ensure the server has adequate memory for the stream","Delete any partial stream left behind and retry the restore once storage is healthy"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if freeDisk(storeDir) < nstate.Bytes || isReadOnly(storeDir) {\n    return fmt.Errorf(\"store not ready for restore compaction\")\n}","typeGuard":null,"tryCatchPattern":"mset, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    if strings.Contains(err.Error(), \"error purging stream\") {\n        // inspect store health (disk space, perms) before retrying\n    }\n    return err\n}","preventionTips":["Keep the JetStream store volume writable with ample free space","Sanity-check state.json FirstSeq before restoring hand-modified snapshots","Monitor storage health (SMART, mount ro flags) on restore targets","For MemoryStorage streams, provision adequate server memory"],"tags":["jetstream","stream-restore","storage","compact"],"backgroundTag":"storage-io-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}