quickwit-oss/tantivy · error · io::Error

Invalid doc store version {v}

Error message

Invalid doc store version {v}

What it means

Thrown during deserialization of DocStoreVersion when the u32 read from the file is neither 1 (V1) nor 2 (V2). The library only understands these doc store format versions; anything else means the file was written by an incompatible tantivy version or the bytes are misaligned/corrupt.

Source

Thrown at src/store/reader.rs:53

impl Display for DocStoreVersion {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            DocStoreVersion::V1 => write!(f, "V1"),
            DocStoreVersion::V2 => write!(f, "V2"),
        }
    }
}
impl BinarySerializable for DocStoreVersion {
    fn serialize<W: io::Write + ?Sized>(&self, writer: &mut W) -> io::Result<()> {
        (*self as u32).serialize(writer)
    }

    fn deserialize<R: io::Read>(reader: &mut R) -> io::Result<Self> {
        Ok(match u32::deserialize(reader)? {
            1 => DocStoreVersion::V1,
            2 => DocStoreVersion::V2,
            v => {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    format!("Invalid doc store version {v}"),
                ))
            }
        })
    }
}

/// Reads document off tantivy's [`Store`](./index.html)
pub struct StoreReader {
    decompressor: Decompressor,
    doc_store_version: DocStoreVersion,
    data: FileSlice,
    skip_index: Arc<SkipIndex>,
    space_usage: StoreSpaceUsage,
    cache: BlockCache,
}

View on GitHub (pinned to b5d8deb80c)

Solutions

  1. Read the index with the same (or newer, compatible) tantivy version that wrote it
  2. Rebuild the index with your current tantivy version if a downgrade is required
  3. Verify the segment file is intact and not corrupted/misaligned
  4. Check your index directory does not mix files from different tantivy versions

Example fix

// before
let version = DocStoreVersion::deserialize(&mut reader)?;
// after
let version = match DocStoreVersion::deserialize(&mut reader) {
    Ok(v) => v,
    Err(e) if e.kind() == io::ErrorKind::InvalidData => {
        eprintln!("incompatible doc store version, rebuilding index");
        return rebuild_index();
    }
    Err(e) => return Err(e),
};
Defensive patterns

Strategy: validation

Validate before calling

fn read_docstore_version(reader: &mut impl std::io::Read) -> std::io::Result<u32> {
    let mut buf = [0u8; 4];
    reader.read_exact(&mut buf)?;
    let v = u32::from_le_bytes(buf);
    if v != 1 && v != 2 {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("unsupported doc store version {v}; this tantivy supports 1..=2"),
        ));
    }
    Ok(v)
}

Type guard

fn is_supported_docstore_version(v: u32) -> bool {
    matches!(v, 1 | 2)
}

Try / catch

match DocStoreVersion::deserialize(&mut reader) {
    Err(e) if e.kind() == std::io::ErrorKind::InvalidData
        && e.to_string().starts_with("Invalid doc store version") => {
        eprintln!("index written by incompatible tantivy; re-index required");
    }
    Err(e) => return Err(e.into()),
    Ok(v) => use_version(v),
}

Prevention

When it happens

Trigger: Opening an index written by a newer tantivy that uses a doc store version beyond V2; reading a corrupted or misaligned byte stream as the version field; pointing the reader at a non-doc-store file.

Common situations: Upgrading/downgrading tantivy across incompatible format versions; mixing segments written by different library versions in one directory; file corruption shifting the read offset.

Related errors

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