GitoxideLabs/gitoxide · error

run length word offset exceeds u32::MAX

Error message

run length word offset exceeds u32::MAX

What it means

`EwahBitmap::write_to` stores the run-length-word (RLW) offset as a `u32` in the EWAH format. If the bitmap's `rlw` offset value exceeds `u32::MAX`, it cannot be encoded, so `write_to` returns an `io::Error` of kind `InvalidInput` rather than emitting a structurally invalid stream.

Solutions

  1. Verify `bitmap.rlw <= u32::MAX as usize` before writing and fail early with a clear error
  2. Keep bitmaps within representable size (chunk them) and recompute the RLW offset per chunk
  3. Audit bitmap construction for bugs that could push the RLW offset out of range

Example fix

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

Strategy: validation

Validate before calling

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

Prevention

When it happens

Trigger: Calling `write_to` on a bitmap whose `rlw` field (position of the run-length word) is greater than `u32::MAX` — implied by a word list of more than ~4.29 billion words.

Common situations: Same extreme-scale scenarios as the word-count overflow: a pathologically large bitmap built from unbounded accumulation or a bug that sets an invalid RLW offset.

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/eb807cd8254aca63. Report an issue: GitHub.

Appendix: source

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

            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.
        ///
        /// The index is sequential like in any other vector.
        pub fn for_each_set_bit(&self, mut f: impl FnMut(usize) -> Option<()>) -> Option<()> {

View on GitHub (pinned to e73179060b)