What causes "interface offset fits u32" in BoundaryML/baml?

Audit the pooling loop for duplicate assignment of the same interface object to a unit (dedup key bug).

interface offset fits u32

Error message

interface offset fits u32

What it means

A Rust `expect("interface offset fits u32")` panic in baml_compiler2_emit's local-unit packing code. While distributing pooled interface objects into per-unit local pools, the next interface offset (`units[u].interfaces.len()`) is converted to `u32`; the compiler assumes each unit holds fewer than 2^32 interfaces. Exceeding that indicates runaway or duplicated pooling, so the library panics rather than truncating offsets.

Source

Thrown at baml_language/crates/baml_compiler2_emit/src/lib.rs:2445

    for (offset, kind) in obj_kind.iter().enumerate() {
        let idx = prefix_objects + offset;
        let u = obj_owner[idx];
        let obj = program.objects[ObjectIndex::from_raw(idx)].clone();
        let local_ref = match kind {
            PoolObjKind::Class => {
                let off = units[u].classes.len();
                units[u].classes.push(obj);
                LocalRef::Class(u32::try_from(off).expect("class offset fits u32"))
            }
            PoolObjKind::Enum => {
                let off = units[u].enums.len();
                units[u].enums.push(obj);
                LocalRef::Enum(u32::try_from(off).expect("enum offset fits u32"))
            }
            PoolObjKind::Interface => {
                let off = units[u].interfaces.len();
                units[u].interfaces.push(obj);
                LocalRef::Interface(u32::try_from(off).expect("interface offset fits u32"))
            }
            PoolObjKind::TypeAlias => {
                let off = units[u].type_alias_objects.len();
                units[u].type_alias_objects.push(obj);
                LocalRef::TypeAlias(u32::try_from(off).expect("type-alias offset fits u32"))
            }
            PoolObjKind::NamedFn(_) | PoolObjKind::CodeAnon => {
                let off = units[u].code.len();
                units[u].code.push(obj);
                LocalRef::Code(u32::try_from(off).expect("code offset fits u32"))
            }
        };
        obj_localref.push(local_ref);
    }

    // ---- Global slot -> owner + local flat index ----------------------------
    // slot -> fq name (functions, interface bodies, and lets).
    let mut slot_to_name: Vec<Option<String>> = vec![None; program.globals.len()];

View on GitHub (pinned to bd85ce9dee)

Solutions

Audit the pooling loop for duplicate assignment of the same interface object to a unit (dedup key bug).
Add an explicit capacity check that emits a proper compile diagnostic before exceeding u32 capacity.
Widen the offset storage to `u64`/`usize` in `LocalRef` and serialized unit format if huge inputs must be supported.
Inspect the input program's interface count; a legitimate program cannot approach 2^32 interfaces.

Example fix

// before
let off = units[u].interfaces.len();
units[u].interfaces.push(obj);
LocalRef::Interface(u32::try_from(off).expect("interface offset fits u32"))
// after
if units[u].interfaces.len() > u32::MAX as usize {
    return Err(EmitError::UnitOverflow { unit: u, kind: "interface" });
}
let off = units[u].interfaces.len();
units[u].interfaces.push(obj);
LocalRef::Interface(off as u32)

Defensive patterns

Strategy: validation

Validate before calling

// Not applicable to BAML users. Embedders can pre-check pool size before packing:
fn interface_pool_within_u32(program: &Program) -> bool {
    program.objects.iter().filter(|o| matches!(o, Object::Interface(_))).count() < u32::MAX as usize
}

Try / catch

// Panics are not catchable from BAML user code. Embedders can isolate compilation:
let result = std::panic::catch_unwind(|| compile(&source));
if result.is_err() {
    report_internal_compiler_error();
}

Prevention

Keep per-unit interface counts below 2^32 by construction (real programs never approach this).
Deduplicate pooled interfaces so each object is pushed to a unit at most once.
Add a compile-time capacity check with a clear diagnostic instead of `expect`.
Fuzz with synthetic large inputs to catch overflow paths early.

When it happens

Trigger: Triggered while assigning `PoolObjKind::Interface` objects to local units when `units[u].interfaces.len()` exceeds `u32::MAX` — only reachable with an absurdly large or pathologically duplicated interface pool.

Common situations: Not hit by real BAML programs; appears in fuzzing or compiler-dev contexts such as a dedup failure pushing interfaces repeatedly, or synthetic inputs with billions of interface declarations.

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