{"record":{"id":"8daac0f50127b44f","repo":"nats-io/nats-server","slug":"error-adding-stream-w","errorCode":null,"errorMessage":"error adding stream: %w","messagePattern":"error adding stream: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":372,"sourceCode":"\t\t}\n\t\treturn nil\n\t}\n\n\treserveCfg := cfg\n\treserveCfg.MaxBytes = max(reserveCfg.MaxBytes, restoreRemaining)\n\tjs.mu.RLock()\n\terr = js.checkAllLimits(&selected, tier, &reserveCfg, reserved, 0)\n\tjs.mu.RUnlock()\n\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 {","sourceCodeStart":354,"sourceCodeEnd":390,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L354-L390","documentation":"After limits checks pass, the server creates the stream in 'restore mode' via addStreamForRestore. If stream creation fails (name conflict, config rejected at store level, storage allocation failure), RestoreStreamV2 wraps the cause. Note: an exact stream-name conflict is detected earlier with JSStreamNameExistRestoreFailedError, so this wrapper usually reflects lower-level store/creation errors.","triggerScenarios":"addStreamForRestore fails because the store cannot create the stream: storage engine error (file perms, disk full at FS level), invalid config that slipped past earlier checks (e.g. duplicate subjects handled differently per storage backend), account/stream limits raced with another restore, or the stream was created between the earlier lookupStream check and this call.","commonSituations":"Two operators restoring the same stream concurrently; a stream with the same name created while the restore request was in flight; disk permissions or full filesystem on the JetStream store directory; restoring into an account whose tier limits were just tightened.","solutions":["Read the wrapped cause: if it says stream name already exists, delete the existing stream or restore under a different name","Check the JetStream store directory permissions and free disk/memory for the stream's storage type","Ensure no other restore/create for the same stream name is running; retry after the conflicting operation finishes","Re-run `nats stream info` / check account limits, then retry the restore once resources and naming conflicts are resolved"],"exampleFix":"// before: restore without checking target\nacc.RestoreStreamV2(cfg, r)\n// after: ensure the stream does not already exist and the account has JetStream\nif _, err := acc.LookupStream(cfg.Name); err == nil {\n    return fmt.Errorf(\"stream %q already exists; delete it first\", cfg.Name)\n}\nacc.RestoreStreamV2(cfg, r)","handlingStrategy":"try-catch","validationCode":"if _, err := acc.LookupStream(cfg.Name); err == nil {\n    return fmt.Errorf(\"stream %q exists; delete before restore\", cfg.Name)\n}\nif err := acc.CheckJetStream(); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":"mset, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    var nap ErrAPIResponse\n    if errors.As(err, &nap) {\n        // inspect wrapped API error (e.g. stream exists / limits) and clean up\n    }\n    return fmt.Errorf(\"restore failed adding stream: %w\", err)\n}","preventionTips":["Check for an existing stream with the same name before restoring","Verify account JetStream limits (memory/store) accommodate the snapshot size","Avoid concurrent restores of the same stream name","Ensure store directory permissions and capacity are healthy"],"tags":["jetstream","stream-restore","stream-creation"],"backgroundTag":"stream-create-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}