{"record":{"id":"c10a308067456e25","repo":"nats-io/nats-server","slug":"error-in-state-json-w","errorCode":null,"errorMessage":"error in state.json: %w","messagePattern":"error in state\\.json: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":267,"sourceCode":"\tdec := s2.NewReader(r)\n\ttr := archive.NewReader(dec)\n\n\tvar nstate StreamState\n\n\t// Load the stream state.\n\thdr, err := tr.Next()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif hdr.Name != \"state.json\" {\n\t\treturn nil, fmt.Errorf(\"expected state.json first\")\n\t}\n\tstate, err := io.ReadAll(tr)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"expected state.json contents\")\n\t}\n\tif err := json.Unmarshal(state, &nstate); err != nil {\n\t\treturn nil, fmt.Errorf(\"error in state.json: %w\", err)\n\t}\n\n\ts, jsa, err := a.checkForJetStream()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tjs := jsa.js\n\tif js == nil {\n\t\treturn nil, NewJSNotEnabledForAccountError()\n\t}\n\tif _, err := a.lookupStream(ncfg.Name); err == nil {\n\t\treturn nil, NewJSStreamNameExistRestoreFailedError()\n\t}\n\n\tcfg, apiErr := s.checkStreamCfg(ncfg, a, false)\n\tif apiErr != nil {\n\t\treturn nil, apiErr\n\t}","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L249-L285","documentation":"The state.json entry bytes could not be parsed as JSON into StreamState. RestoreStreamV2 wraps the json.Unmarshal error, so the actual syntax/type error is included via %w. This means the snapshot's metadata file is present and readable but not valid stream-state JSON.","triggerScenarios":"The state.json entry contains invalid JSON: the file was hand-edited, produced by an incompatible server version with a different schema, written by a non-nats tool, or corrupted in a way that survived decompression (bit rot, bad re-encoding, HTML/error page written into the file).","commonSituations":"Manually editing state.json to tweak FirstSeq/subjects and introducing a syntax error; restoring a snapshot from a much older/newer nats-server with schema drift; a proxy or misconfigured upload writing an error page as the file body; locale/encoding mangling during transfer.","solutions":["Read the wrapped JSON error in the message to locate the syntax/type problem and fix state.json (valid JSON, correct StreamState fields)","Re-generate the snapshot from the source stream instead of hand-crafting state.json","Align nats-server versions between backup and restore hosts (use the same or newer restore server that understands the schema)","Validate the file offline: gzip/s2-decompress, extract the first entry, and run it through json.Unmarshal/`go json.tool`"],"exampleFix":"// before: hand-edited state.json with a trailing comma\n{\"FirstSeq\": 42, \"Msgs\": 100,}\n// after: valid JSON matching StreamState\n{\"FirstSeq\": 42, \"Msgs\": 100, \"Bytes\": 8192, \"Consumers\": 0}","handlingStrategy":"validation","validationCode":"var st StreamState\nif err := json.Unmarshal(rawStateJSON, &st); err != nil {\n    return fmt.Errorf(\"state.json invalid: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"var jsErr *json.UnmarshalTypeError\nmset, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    if e, ok := err.(*json.UnmarshalTypeError); ok {\n        errors.As(err, &jsErr)\n        // e.Field/e.Value pinpoint the bad state.json field\n    }\n    return err\n}","preventionTips":["Never hand-edit state.json; regenerate snapshots instead","Run snapshot JSON through a validator before restoring across versions","Keep backup/restore nats-server versions aligned","Reject snapshots whose state.json fails offline unmarshal into StreamState"],"tags":["jetstream","stream-restore","json","schema-validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}