nats-io/nats-server · error

unsupported version: %d

Error message

unsupported version: %d

What it means

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.

Source

Thrown at server/filestore.go:14085

	err = cfs.fs.writeFileWithOptionalSync(sum, []byte(checksum), defaultFilePerms)
	if err != nil {
		return err
	}
	return nil
}

// Consumer version.
func checkConsumerHeader(hdr []byte) (uint8, error) {
	if len(hdr) < 2 || hdr[0] != magic {
		return 0, errCorruptState
	}
	version := hdr[1]
	switch version {
	case 1, 2:
		return version, nil
	}
	return 0, fmt.Errorf("unsupported version: %d", version)
}

func (o *consumerFileStore) copyPending() map[uint64]*Pending {
	pending := make(map[uint64]*Pending, len(o.state.Pending))
	for seq, p := range o.state.Pending {
		pending[seq] = &Pending{p.Sequence, p.Timestamp}
	}
	return pending
}

func (o *consumerFileStore) copyRedelivered() map[uint64]uint64 {
	redelivered := make(map[uint64]uint64, len(o.state.Redelivered))
	for seq, dc := range o.state.Redelivered {
		redelivered[seq] = dc
	}
	return redelivered
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Run a nats-server version equal to or newer than the one that wrote the store directory before downgrading
2. Use the nats-server Stream/Consumer upgrade path; don't roll back JetStream storage versions
3. If the header is corrupt, delete/rebuild the affected consumer (messages remain in the stream)
4. Back up and consult the JetStream migration notes before version changes

Example fix

// before
// nats-server v2.10 binary opening a store written by v2.11+
// error: unsupported version: 3
// after
// upgrade the binary first:
// nats-server --version  (ensure >= writer version), then restart

// before starting server against a JetStream dir:
// ensure binary version >= version that wrote the store
// nats-server -v  and compare with your upgrade records
if runtimeVersion < storeWriterVersion {
	return fmt.Errorf("refusing to open store written by newer server %s", storeWriterVersion)
}

func supportedBlockVersion(v byte) bool { return v == 1 || v == 2 }

if err := startServer(); err != nil {
	if strings.Contains(err.Error(), "unsupported version") {
		// upgrade binary to the writer's version; do not delete data blindly
	}
	return err
}

When it happens

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

Common situations: 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.

Related errors

• compression algorithm not known
• ErrBadVersion
• unknown compression algorithm
• name required
• fileStore requires file storage type in config

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