What causes "retained size does not fit usize" in BoundaryML/baml?

Fix the producer to emit valid non-negative retained_size_bytes

retained size does not fit usize

Error message

retained size does not fit usize

What it means

Same class as the original-size check: ValueMetadataV1.retained_size_bytes is converted to usize during the TryFrom conversion, and a negative or usize-overflowing value makes the conversion fail with InvalidData and this message.

Source

Thrown at baml_language/crates/bex_events/src/value/record.rs:193

            id: metadata.id,
            codec,
            availability,
            original_size_bytes: metadata
                .original_size_bytes
                .map(usize::try_from)
                .transpose()
                .map_err(|_| {
                    io::Error::new(
                        io::ErrorKind::InvalidData,
                        "original size does not fit usize",
                    )
                })?,
            retained_size_bytes: metadata
                .retained_size_bytes
                .map(usize::try_from)
                .transpose()
                .map_err(|_| {
                    io::Error::new(
                        io::ErrorKind::InvalidData,
                        "retained size does not fit usize",
                    )
                })?,
            diagnostic: metadata.diagnostic,
        })
    }
}

impl From<&ValueRef> for crate::value::pb::ValueMetadataV1 {
    fn from(value_ref: &ValueRef) -> Self {
        Self {
            id: value_ref.id.clone(),
            codec: match value_ref.codec {
                ValueCodec::BamlOutboundValue => {
                    crate::value::pb::ValueCodec::BamlOutboundValue as i32
                }
            },

View on GitHub (pinned to bd85ce9dee)

Solutions

Fix the producer to emit valid non-negative retained_size_bytes
Run the reader on a 64-bit platform when values are legitimately large
Skip/flag records with implausible retained sizes during ingest instead of failing the whole stream
Sanitize the proto (reject or None-out out-of-range sizes) before conversion

Example fix

// before
let size = md.retained_size_bytes.unwrap_or_default();
// after
let size = u64::try_from(md.retained_size_bytes.unwrap_or_default()).ok().filter(|s| *s <= usize::MAX as u64);

Defensive patterns

Strategy: type-guard

Validate before calling

fn retained_fits(v: Option<i64>) -> bool { v.map_or(true, |s| s >= 0 && (s as u64) <= usize::MAX as u64) }

Type guard

fn valid_retained_size(md: &pb::ValueMetadataV1) -> bool { md.retained_size_bytes.map_or(true, |s| s >= 0) }

Try / catch

ValueRecord::try_from(md).map_err(|e| if e.to_string().contains("retained size") { CorruptionKind::BadSize.into() } else { e })

Prevention

Clamp retained sizes to realistic bounds at the writer
Reject negative sizes at serialization time
Run cross-platform (32/64-bit) reader tests on large traces

When it happens

Trigger: Decoding a ValueMetadataV1 with retained_size_bytes negative (e.g. -1 sentinel from a buggy writer) or exceeding usize::MAX on narrow platforms.

Common situations: Corrupted trace files, 32-bit readers consuming 64-bit-written traces, writer bugs emitting sentinel or uninitialized size fields.

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 BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/f8b236c5634bac71. Report an issue: GitHub.