quickwit-oss/tantivy · critical

actual doc store version: {doc_store_version}, max_supported

Error message

actual doc store version: {doc_store_version}, max_supported: {DOC_STORE_VERSION}

What it means

Footer::deserialize reads the DocStoreVersion from a segment footer and panics if it is greater than the max version (DOC_STORE_VERSION) this library build supports. This is a forward-compatibility guard: the on-disk format is newer than the reader. Downgrading the library under data written by a newer tantivy triggers it.

Source

Thrown at src/store/footer.rs:31

}

/// Serialises the footer to a byte-array
/// - offset : 8 bytes
/// - compressor id: 1 byte
/// - reserved for future use: 15 bytes
impl BinarySerializable for DocStoreFooter {
    fn serialize<W: io::Write + ?Sized>(&self, writer: &mut W) -> io::Result<()> {
        BinarySerializable::serialize(&DOC_STORE_VERSION, writer)?;
        BinarySerializable::serialize(&self.offset, writer)?;
        BinarySerializable::serialize(&self.decompressor.get_id(), writer)?;
        writer.write_all(&[0; 15])?;
        Ok(())
    }

    fn deserialize<R: io::Read>(reader: &mut R) -> io::Result<Self> {
        let doc_store_version = DocStoreVersion::deserialize(reader)?;
        if doc_store_version > DOC_STORE_VERSION {
            panic!(
                "actual doc store version: {doc_store_version}, max_supported: {DOC_STORE_VERSION}"
            );
        }
        let offset = u64::deserialize(reader)?;
        let compressor_id = u8::deserialize(reader)?;
        let mut skip_buf = [0; 15];
        reader.read_exact(&mut skip_buf)?;
        Ok(DocStoreFooter {
            offset,
            doc_store_version,
            decompressor: Decompressor::from_id(compressor_id),
        })
    }
}

impl FixedSize for DocStoreFooter {
    const SIZE_IN_BYTES: usize = 28;
}

View on GitHub (pinned to b5d8deb80c)

Solutions

1. Upgrade tantivy to a version whose DOC_STORE_VERSION >= the file's version (check the footer value in the panic message)
2. Re-index the data with the older library version if downgrade is mandatory
3. Ensure all services sharing an index run the same tantivy version
4. Keep backups/reindex pipelines so format upgrades can be rolled forward

Example fix

// before
// panic: actual doc store version: 3, max_supported: 2  (tantivy 0.21 reading 0.22 data)
// after (Cargo.toml)
tantivy = "0.22" // match the version that wrote the index

let current: u32 = tantivy_version_doc_store_version(); // must be >= footer version
let file_version: u32 = read_footer_version(path)?;
if file_version > current {
    return Err(format!("index written by newer tantivy: v{file_version} > supported v{current}"));
}

When it happens

Trigger: Opening a doc store/segment footer whose version byte/integer exceeds DOC_STORE_VERSION of the current crate version — i.e. data written by a newer tantivy release read by an older one.

Common situations: Downgrading the tantivy dependency while old indexes remain on disk; a writer service upgraded before reader services sharing the same data directory; using an old library build against files produced by a dev branch.

Related errors

• unknown compressor id {id:?}
• FastFieldsPlugin is a built-in; use FastFieldsPluginWriter::
• Invalid doc store version {v}
• Exist query without a field isn't allowed
• All columns re required to be numerical

AI-assisted analysis of quickwit-oss/tantivy@b5d8deb80c (2026-09-05). Data as JSON: /api/errors/224fd5d9be1d5b9d. Report an issue: GitHub.