{"record":{"id":"a44835a4051138b7","repo":"nats-io/nats-server","slug":"unsupported-version-d","errorCode":null,"errorMessage":"unsupported version: %d","messagePattern":"unsupported version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/filestore.go","lineNumber":14085,"sourceCode":"\n\terr = cfs.fs.writeFileWithOptionalSync(sum, []byte(checksum), defaultFilePerms)\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn nil\n}\n\n// Consumer version.\nfunc checkConsumerHeader(hdr []byte) (uint8, error) {\n\tif len(hdr) < 2 || hdr[0] != magic {\n\t\treturn 0, errCorruptState\n\t}\n\tversion := hdr[1]\n\tswitch version {\n\tcase 1, 2:\n\t\treturn version, nil\n\t}\n\treturn 0, fmt.Errorf(\"unsupported version: %d\", version)\n}\n\nfunc (o *consumerFileStore) copyPending() map[uint64]*Pending {\n\tpending := make(map[uint64]*Pending, len(o.state.Pending))\n\tfor seq, p := range o.state.Pending {\n\t\tpending[seq] = &Pending{p.Sequence, p.Timestamp}\n\t}\n\treturn pending\n}\n\nfunc (o *consumerFileStore) copyRedelivered() map[uint64]uint64 {\n\tredelivered := make(map[uint64]uint64, len(o.state.Redelivered))\n\tfor seq, dc := range o.state.Redelivered {\n\t\tredelivered[seq] = dc\n\t}\n\treturn redelivered\n}\n","sourceCodeStart":14067,"sourceCodeEnd":14103,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/filestore.go#L14067-L14103","documentation":"The consumer filestore's block header carries a format version byte; checkBlockVersion (server/filestore.go) accepts versions 1 and 2 only. Any other version byte means the block file was written by an incompatible (usually newer or corrupt) nats-server and cannot be interpreted by this build.","triggerScenarios":"Opening a consumer state block file whose header version byte is not 1 or 2 — e.g. a data directory written by a newer nats-server major release, or a corrupted header where the version byte was overwritten.","commonSituations":"Downgrading nats-server below the version that wrote the JetStream data; copying store dirs from a newer cluster to an older one; disk corruption flipping header bytes; third-party tooling rewriting block files.","solutions":["Run a nats-server version equal to or newer than the one that wrote the store directory before downgrading","Use the nats-server Stream/Consumer upgrade path; don't roll back JetStream storage versions","If the header is corrupt, delete/rebuild the affected consumer (messages remain in the stream)","Back up and consult the JetStream migration notes before version changes"],"exampleFix":"// before\n// nats-server v2.10 binary opening a store written by v2.11+\n// error: unsupported version: 3\n// after\n// upgrade the binary first:\n// nats-server --version  (ensure >= writer version), then restart","handlingStrategy":"validation","validationCode":"// before starting server against a JetStream dir:\n// ensure binary version >= version that wrote the store\n// nats-server -v  and compare with your upgrade records\nif runtimeVersion < storeWriterVersion {\n\treturn fmt.Errorf(\"refusing to open store written by newer server %s\", storeWriterVersion)\n}","typeGuard":"func supportedBlockVersion(v byte) bool { return v == 1 || v == 2 }","tryCatchPattern":"if err := startServer(); err != nil {\n\tif strings.Contains(err.Error(), \"unsupported version\") {\n\t\t// upgrade binary to the writer's version; do not delete data blindly\n\t}\n\treturn err\n}","preventionTips":["Never downgrade nats-server across JetStream storage format changes","Back up the store dir before upgrades","Test version changes in staging with a copy of the store","Keep upgrade/downgrade notes per cluster"],"tags":["jetstream","filestore","versioning","compatibility"],"backgroundTag":"unsupported-storage-version","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}