What causes "bit word count exceeds u32::MAX" in GitoxideLabs/gitoxide?

Split the bitmap into chunks smaller than u32::MAX words and write each separately

bit word count exceeds u32::MAX

Error message

bit word count exceeds u32::MAX

What it means

`EwahBitmap::write_to` serializes the bitmap's word list, and the EWAH format stores the word count as a `u32`. When the bitmap contains more than `u32::MAX` (~4.29 billion) words, the count cannot be encoded, so `write_to` returns an `io::Error` of kind `InvalidInput` instead of writing a corrupt file.

Solutions

Split the bitmap into chunks smaller than u32::MAX words and write each separately
Check `bitmap.bits.len() <= u32::MAX` before writing and fail early with your own error
Investigate upstream logic that grows the bitmap unboundedly; real Git index bitmaps never approach this size

Example fix

// before
bitmap.write_to(&mut out)?;
// after
assert!(bitmap.bits.len() <= u32::MAX as usize, "bitmap too large for EWAH");
bitmap.write_to(&mut out)?;

Defensive patterns

Strategy: validation

Validate before calling

if bitmap.bits.len() > u32::MAX as usize {
    return Err(io::Error::new(io::ErrorKind::InvalidInput, "bitmap too large"));
}

Prevention

Cap bitmap size at construction time
Chunk very large bitmaps before serialization
Treat word counts near u32::MAX as a bug indicator

When it happens

Trigger: Calling `write_to` on a bitmap whose `bits` vector length exceeds `u32::MAX`, i.e. an absurdly large bitmap (each word covers 64 bits, so >2^38 bits).

Common situations: Practically only reached with unbounded accumulation into a bitmap from a huge or buggy input source, or on 64-bit systems where memory allows constructing such a vector.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/525b89c1533c53ed. Report an issue: GitHub.

Appendix: source

Thrown at gix-bitmap/src/ewah.rs:78

                })
                .collect();
            let num_bits = bits.len().try_into().ok()?;

            Some(Vec {
                num_bits,
                bits: std::iter::once((literal_words.len() as u64) << (1 + RLW_RUNNING_BITS))
                    .chain(literal_words)
                    .collect(),
                rlw: 0,
            })
        }

        /// Write the bitmap as EWAH bytes to `out`.
        ///
        /// These bytes can be parsed again with [`decode()`](super::decode()).
        pub fn write_to(&self, out: &mut impl std::io::Write) -> std::io::Result<()> {
            let len: u32 = self.bits.len().try_into().map_err(|_| {
                std::io::Error::new(std::io::ErrorKind::InvalidInput, "bit word count exceeds u32::MAX")
            })?;
            let rlw: u32 = self.rlw.try_into().map_err(|_| {
                std::io::Error::new(
                    std::io::ErrorKind::InvalidInput,
                    "run length word offset exceeds u32::MAX",
                )
            })?;

            out.write_all(&self.num_bits.to_be_bytes())?;
            out.write_all(&len.to_be_bytes())?;
            for word in &self.bits {
                out.write_all(&word.to_be_bytes())?;
            }
            out.write_all(&rlw.to_be_bytes())
        }

        /// Call `f(index)` for each bit that is true, given the index of the bit that identifies it uniquely within the bit array.
        /// If `f` returns `None` the iteration will be stopped and `None` is returned.

View on GitHub (pinned to e73179060b)