{"record":{"id":"c84374bf86c597ea","repo":"nats-io/nats-server","slug":"failed-to-activate-stream-q-w","errorCode":null,"errorMessage":"failed to activate stream %q: %w","messagePattern":"failed to activate stream %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":381,"sourceCode":"\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif err := checkUsageLimits(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tmset, err := a.addStreamForRestore(&cfg)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error adding stream: %w\", err)\n\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 {","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L363-L399","documentation":"When the restore payload finishes, the deferred completeRestore() call flips the stream from restore mode to fully active (sealing state, publishing internal notices, switching the store). If that activation fails, the error is wrapped as 'failed to activate stream' and becomes the restore's return error, while a warning is logged. Messages may have been written but the stream is left incomplete/unusable.","triggerScenarios":"mset.completeRestore() returns an error: typically the underlying store's activation step fails (file-system error persisting final state), the stream was somehow invalidated mid-restore, or cluster/Raft metadata update for the restored stream fails in clustered mode.","commonSituations":"Disk full or I/O error on the JetStream store during the final state write; server shutting down mid-restore; cluster member failing while updating stream assignment; storage backend bug when re-opening a restored stream for publishing.","solutions":["Check the server log line 'failed to activate stream' for the wrapped cause (store/IO vs cluster)","Free disk space / fix store directory permissions, then delete the partially restored stream and re-run the restore","In clustered mode, ensure a quorum is healthy before retrying the restore","If the stream exists but is unusable after a failed activation, delete it (`nats stream rm`) and restore again"],"exampleFix":"// before: blind retry after activation failure\nacc.RestoreStreamV2(cfg, r)\n// after: clean up the half-activated stream, then retry\nif _, err := acc.RestoreStreamV2(cfg, r); err != nil {\n    if strings.Contains(err.Error(), \"failed to activate stream\") {\n        jsDeleteStream(account, cfg.Name) // remove unusable partial stream\n        return acc.RestoreStreamV2(cfg, freshReader())\n    }\n    return err\n}","handlingStrategy":"retry","validationCode":"// ensure cluster quorum and disk headroom before restoring\nif !jsClusterHealthy() || freeDisk(storeDir) < snapshotBytes*2 {\n    return fmt.Errorf(\"preconditions for stream activation not met\")\n}","typeGuard":null,"tryCatchPattern":"mset, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to activate stream\") {\n        jsDeleteStream(account, cfg.Name) // remove unusable partial stream\n        time.Sleep(backoff)\n        return acc.RestoreStreamV2(cfg, freshReader()) // bounded retry\n    }\n    return err\n}","preventionTips":["Maintain disk headroom (roughly 2x snapshot size) on the store volume","Avoid shutting down the server during restores","Verify Raft/quorum health before restoring in clustered mode","Clean up partial streams after any failed activation before retrying"],"tags":["jetstream","stream-restore","activation","storage"],"backgroundTag":"stream-activation-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}