{"record":{"id":"61b85e43950b75f8","repo":"nats-io/nats-server","slug":"errbadversion","errorCode":"ErrBadVersion","errorMessage":"ss: bad version","messagePattern":"ss: bad version","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/avl/seqset.go","lineNumber":308,"sourceCode":"\tle.PutUint32(buf[i+4:], uint32(ss.size))\n\ti += 8\n\tss.root.nodeIter(func(n *node) {\n\t\tle.PutUint64(buf[i:], n.base)\n\t\ti += 8\n\t\tfor _, b := range n.bits {\n\t\t\tle.PutUint64(buf[i:], b)\n\t\t\ti += 8\n\t\t}\n\t\tle.PutUint16(buf[i:], uint16(n.h))\n\t\ti += 2\n\t})\n\treturn buf[:i]\n}\n\n// ErrBadEncoding is returned when we can not decode properly.\nvar (\n\tErrBadEncoding = errors.New(\"ss: bad encoding\")\n\tErrBadVersion  = errors.New(\"ss: bad version\")\n\tErrSetNotEmpty = errors.New(\"ss: set not empty\")\n)\n\n// Decode returns the sequence set and number of bytes read from the buffer on success.\nfunc Decode(buf []byte) (*SequenceSet, int, error) {\n\tif len(buf) < minLen || buf[0] != magic {\n\t\treturn nil, -1, ErrBadEncoding\n\t}\n\n\tswitch v := buf[1]; v {\n\tcase 1:\n\t\treturn decodev1(buf)\n\tcase 2:\n\t\treturn decodev2(buf)\n\tdefault:\n\t\treturn nil, -1, ErrBadVersion\n\t}\n}","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/avl/seqset.go#L290-L326","documentation":"ErrBadVersion is returned by SequenceSet Decode when the buffer has a valid magic byte but an unrecognized encoding version byte. The decoder supports specific versions (e.g. dispatching to decodev1/decodev2); anything else is rejected so future formats fail loudly instead of misparsing.","triggerScenarios":"Decode receives a buffer with an unsupported value in the version position — typically data written by a newer library version than the one decoding it.","commonSituations":"Rollback/downgrade of the server or client library after state files were written in a newer format, or hand-crafted/corrupt buffers.","solutions":["Upgrade the library/server to a version that supports the encoding version in the buffer","Regenerate the state data with the current version if downgrade is intentional","Confirm the buffer wasn't assembled from mixed encodings"],"exampleFix":"// before\ngo get github.com/nats-io/nats-server@v2.9.0 // older, can't decode v2 encodings\n// after\ngo get -u github.com/nats-io/nats-server","handlingStrategy":"try-catch","validationCode":"if len(buf) >= 2 {\n    version := buf[1]\n    if version > supportedMaxVersion {\n        return fmt.Errorf(\"encoded data version %d newer than supported\", version)\n    }\n}","typeGuard":null,"tryCatchPattern":"ss, n, err := avl.Decode(buf)\nif errors.Is(err, avl.ErrBadVersion) {\n    return fmt.Errorf(\"sequence set written by newer version; upgrade the server\")\n}","preventionTips":["Keep server/library versions consistent across rollouts","Avoid downgrades below the version that wrote persisted state files","Pin versions in deployment pipelines"],"tags":["serialization","versioning","encoding","compatibility","go"],"backgroundTag":"unsupported-format-version","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}