nats-io/nats-server · error

ErrBadVersion

ErrBadVersion

Error message

ss: bad version

What it means

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.

Source

Thrown at server/avl/seqset.go:308

	le.PutUint32(buf[i+4:], uint32(ss.size))
	i += 8
	ss.root.nodeIter(func(n *node) {
		le.PutUint64(buf[i:], n.base)
		i += 8
		for _, b := range n.bits {
			le.PutUint64(buf[i:], b)
			i += 8
		}
		le.PutUint16(buf[i:], uint16(n.h))
		i += 2
	})
	return buf[:i]
}

// ErrBadEncoding is returned when we can not decode properly.
var (
	ErrBadEncoding = errors.New("ss: bad encoding")
	ErrBadVersion  = errors.New("ss: bad version")
	ErrSetNotEmpty = errors.New("ss: set not empty")
)

// Decode returns the sequence set and number of bytes read from the buffer on success.
func Decode(buf []byte) (*SequenceSet, int, error) {
	if len(buf) < minLen || buf[0] != magic {
		return nil, -1, ErrBadEncoding
	}

	switch v := buf[1]; v {
	case 1:
		return decodev1(buf)
	case 2:
		return decodev2(buf)
	default:
		return nil, -1, ErrBadVersion
	}
}

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Upgrade the library/server to a version that supports the encoding version in the buffer
  2. Regenerate the state data with the current version if downgrade is intentional
  3. Confirm the buffer wasn't assembled from mixed encodings

Example fix

// before
go get github.com/nats-io/nats-server@v2.9.0 // older, can't decode v2 encodings
// after
go get -u github.com/nats-io/nats-server
Defensive patterns

Strategy: try-catch

Validate before calling

if len(buf) >= 2 {
    version := buf[1]
    if version > supportedMaxVersion {
        return fmt.Errorf("encoded data version %d newer than supported", version)
    }
}

Try / catch

ss, n, err := avl.Decode(buf)
if errors.Is(err, avl.ErrBadVersion) {
    return fmt.Errorf("sequence set written by newer version; upgrade the server")
}

Prevention

When it happens

Trigger: 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.

Common situations: Rollback/downgrade of the server or client library after state files were written in a newer format, or hand-crafted/corrupt buffers.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/61b85e43950b75f8. Report an issue: GitHub.