quickwit-oss/tantivy · error

The term has an invalid type code

Error message

The term has an invalid type code

What it means

`Term::typ()` reads the first byte of the term's raw byte representation as a type code and converts it with `Type::from_code`, panicking via `expect("The term has an invalid type code")` if the byte is not a known code. `Type::from_code` only recognizes the codes defined in `type_codes` (TEXT=0, U64=1, etc.), so any term whose leading byte falls outside that set triggers the panic. Many accessors (`get_fast_type`, `as_str`, `as_facet`, `as_bytes`, `as_ip_addr`, `as_json`) call `typ()` and inherit this panic.

Source

Thrown at src/schema/term.rs:324

where B: AsRef<[u8]>
{
    /// Wraps a object holding bytes
    pub fn wrap(data: B) -> ValueBytes<B> {
        ValueBytes(data)
    }

    /// Wraps a object holding Vec<u8>
    pub fn to_owned(&self) -> ValueBytes<Vec<u8>> {
        ValueBytes(self.0.as_ref().to_vec())
    }

    fn typ_code(&self) -> u8 {
        self.0.as_ref()[0]
    }

    /// Return the type of the term.
    pub fn typ(&self) -> Type {
        Type::from_code(self.typ_code()).expect("The term has an invalid type code")
    }

    /// Returns the `u64` value stored in a term.
    ///
    /// Returns `None` if the term is not of the u64 type, or if the term byte representation
    /// is invalid.
    pub fn as_u64(&self) -> Option<u64> {
        self.get_fast_type::<u64>()
    }

    fn get_fast_type<T: FastValue>(&self) -> Option<T> {
        if self.typ() != T::to_type() {
            return None;
        }
        let value_bytes = self.raw_value_bytes_payload();
        let value_u64 = u64::from_be_bytes(value_bytes.try_into().ok()?);
        Some(T::from_u64(value_u64))
    }

View on GitHub (pinned to b5d8deb80c)

Solutions

1. Validate the first byte of any manually built term against the valid `type_codes` before calling `typ()` or the dependent accessors.
2. Rebuild the index with the same tantivy version that wrote it — a version mismatch in term encoding is the most common cause of corrupt type codes.
3. Check index integrity; if terms come from disk (termdict/PostingFormat), re-index the segment since the data is corrupt.
4. Instead of `typ()`, use `value_bytes()` and interpret bytes yourself, or wrap calls in `catch_unwind` if processing untrusted term bytes.

Example fix

// before: bytes pushed without type-code prefix
let mut term = Term::from_field_u64(field, 0);
term.as_bytes_mut().insert(0, 0xEE); // invalid code

// after: build terms through typed constructors only
let term = Term::from_field_u64(field, 42);
let t = term.typ(); // always a valid Type

const VALID_TYPE_CODES: &[u8] = &[0u8, 1, 2, 3, 4, 5, 6, 7]; // TEXT, U64, I64, F64, DATE, FACET, BYTES, JSON codes
fn term_has_valid_type_code(term: &Term) -> bool {
    let bytes = term.value_bytes();
    !bytes.is_empty() && VALID_TYPE_CODES.contains(&bytes[0])
}

fn safe_typ(term: &Term) -> Option<Type> {
    let code = *term.value_bytes().first()?;
    Type::from_code(code)
}

let typ = std::panic::catch_unwind(|| term.typ())
    .ok()
    .or_else(|| safe_typ(&term))
    .ok_or_else(|| anyhow::anyhow!("term has invalid type code: {:?}", term.value_bytes().first()))?;

When it happens

Trigger: Constructing a `Term` from raw bytes with an invalid leading byte (e.g. `Term::wrap(term_bytes)` or manual byte-level term building), deserializing a corrupt term from an index segment, or offsetting/scrambling term bytes so byte 0 is not a valid type code.

Common situations: Reading an index written by an incompatible tantivy version (type-code layout changed), hand-crafted terms in tests/plugins using `Term::from` on misordered byte buffers, index corruption from partial writes, or custom code that prepends a value to the term without the type-code prefix.

Related errors

• Corrupted data. Invalid VInt 32
• Invalid type code in JSON term
• No multivalued index is allowed when stacking column index
• Internal Error: Called get_val of empty column.
• unsupported

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