What causes "failed to construct RGB image from {width}x{height} buffer" in run-llama/liteparse?

Free memory or reduce the image size; the to_vec() copy can fail under memory pressure.

run-llama/liteparse · error · std::io::Error

failed to construct RGB image from

Error message

failed to construct RGB image from {width}x{height} buffer

What it means

As the final step, rgb_image calls image::RgbImage::from_raw(width, height, vec). Despite the earlier explicit length check, from_raw can still fail (it re-validates that the buffer size matches the dimensions and may hit allocator limits); if it returns None this error is produced. In practice this is a defensive backstop indicating the image crate refused to build the image.

Solutions

Free memory or reduce the image size; the to_vec() copy can fail under memory pressure.
Verify the `image` crate version is the one LiteParse was built against and update if the ecosystem changed.
If it persists, log width/height/buffer length and file an issue with a reproducer.

Defensive patterns

Strategy: try-catch

Try / catch

match ocr.recognize_sync(&buf, w, h) {
    Ok(res) => use(res),
    Err(e) if e.to_string().contains("failed to construct RGB image") => {
        // fall back: retry with smaller image or report OOM
    }
    Err(e) => return Err(e.into()),
}

Prevention

Ensure adequate memory for large image buffers (from_raw copies the data)
Pin compatible versions of the `image` crate in your lockfile
Log dimensions/lengths when this backstop fires to identify the real cause

When it happens

Trigger: Calling the OCR recognize path where dimensions and buffer length pass the earlier checks but image::RgbImage::from_raw still returns None (e.g. allocator failure for the huge to_vec() copy, or an image-crate version whose internal validation rejects the input).

Common situations: Memory exhaustion while copying a very large buffer; mismatches between the liteparse expectation and the installed `image` crate's validation behavior after a dependency upgrade.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of run-llama/liteparse@22d2dd8cd7 (2026-09-08). Data as JSON: /api/errors/ee4d492ae3e7dd76. Report an issue: GitHub.

Appendix: source

Thrown at crates/liteparse/src/ocr/oar.rs:287

        .ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                format!("RGB image dimensions overflow: {width}x{height}"),
            )
        })?;

    if image_data.len() != expected_len {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "invalid RGB buffer length for {width}x{height}: expected {expected_len} bytes, got {}",
                image_data.len()
            ),
        ));
    }

    image::RgbImage::from_raw(width, height, image_data.to_vec()).ok_or_else(|| {
        io::Error::new(
            io::ErrorKind::InvalidInput,
            format!("failed to construct RGB image from {width}x{height} buffer"),
        )
    })
}

fn region_to_result(region: oar_ocr::oarocr::TextRegion) -> Option<OcrResult> {
    let text = region.text?.trim().to_owned();
    let confidence = region.confidence?;
    if text.is_empty() || !confidence.is_finite() {
        return None;
    }

    let points = &region.bounding_box.points;
    if points.is_empty()
        || points
            .iter()
            .any(|point| !point.x.is_finite() || !point.y.is_finite())

View on GitHub (pinned to 22d2dd8cd7)