What causes "ss: bad encoding" in nats-io/nats-server?

Verify the source of the bytes: only pass buffers originally produced by SequenceSet Encode

ErrBadEncoding

ErrBadEncoding

Error message

ss: bad encoding

What it means

ErrBadEncoding is returned by SequenceSet Decode when the buffer cannot be a valid encoded sequence set: it is shorter than the minimum encoding length or does not start with the magic byte. It also guards against a declared node count that exceeds what the buffer could possibly contain, preventing out-of-bounds reads.

Source

Thrown at server/avl/seqset.go:307

	le.PutUint32(buf[i:], uint32(nn))
	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

Verify the source of the bytes: only pass buffers originally produced by SequenceSet Encode
Check buffer length and first byte (magic) before calling Decode
Rebuild the state (e.g. delete and recreate the consumer/stream state) if the file is corrupted
Confirm you are not off-by-one in the buffer slice passed to Decode

Example fix

// before
ss, n, err := avl.Decode(raw[1:]) // skips magic byte
// after
ss, n, err := avl.Decode(raw) // Decode expects the magic byte at buf[0]

Defensive patterns

Strategy: try-catch

Validate before calling

func decodable(buf []byte) bool {
    return len(buf) >= 1 && buf[0] == magicByte // check magic before Decode
}

Try / catch

ss, n, err := avl.Decode(buf)
if errors.Is(err, avl.ErrBadEncoding) {
    log.Warnf("corrupt sequence set (%d bytes); rebuilding state", len(buf))
    ss = avl.NewSequenceSet()
}

Prevention

Only decode buffers produced by Encode
Persist buffers with length prefixes or checksums to detect truncation/corruption
Never slice off bytes (like the magic byte) before Decode

When it happens

Trigger: Calling Decode with a buffer shorter than minLen, whose first byte != magic, or whose node count nn is negative or exceeds (len(buf)-minLen)/((numBuckets+1)*8+2).

Common situations: Reading a truncated or corrupted JetStream state file, decoding bytes that are not a sequence-set encoding (wrong stream/offset), or byte-order/serialization version confusion.

Related errors

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