nats-io/nats-server · warning

bad index file

Error message

bad index file

What it means

Returned when a file-store block index file fails header validation on load: checkNewHeader rejects the file's header block. The store removes the bad index file and returns this error so the caller can trigger an index rebuild.

Source

Thrown at server/filestore.go:10130

		return err
	}

	// Set if first time.
	if mb.liwsz == 0 {
		mb.liwsz = int64(len(buf))
	}

	// Decrypt if needed.
	if mb.aek != nil {
		buf, err = mb.aek.Open(buf[:0], mb.nonce, buf, nil)
		if err != nil {
			return err
		}
	}

	if err := checkNewHeader(buf); err != nil {
		defer os.Remove(ifn)
		return fmt.Errorf("bad index file")
	}

	bi := hdrLen

	// Helpers, will set i to -1 on error.
	readSeq := func() uint64 {
		if bi < 0 {
			return 0
		}
		seq, n := binary.Uvarint(buf[bi:])
		if n <= 0 {
			bi = -1
			return 0
		}
		bi += n
		return seq &^ ebit
	}
	readCount := readSeq

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Simply retry/restart — the index file is deleted automatically and will be rebuilt from the message block.
2. If the server version changed, confirm the data directory matches the current NATS Server version's expectations.
3. If rebuilds keep failing, stop the server, back up the stream dir, and remove *.idx files to force a clean rebuild.
4. Check disk/filesystem integrity if corruption recurs frequently.

if err != nil && strings.Contains(err.Error(), "bad index file") {
    // index was deleted; server rebuilds it automatically — verify stream reads recover
}

When it happens

Trigger: Reading an index file (ifn) whose header fails checkNewHeader — the file's magic/header bytes don't match the expected new-format header.

Common situations: Upgraded/downgraded NATS Server versions writing different index formats, truncated or corrupted index files after power loss, or partially restored data directories from backup.

Related errors

• short index file
• fileStore requires file storage type in config
• filestore max block size is %s
• could not create hash: %v
• rebuildState for block %d failed: %w

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