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

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

enum offset fits u32

Error message

enum offset fits u32

What it means

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

Source

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

            }
        })
        .collect();
    // Per pool object: its LocalRef within its owning unit (bucket + offset).
    let mut obj_localref: Vec<LocalRef> = Vec::with_capacity(tail_start - prefix_objects);
    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);

View on GitHub (pinned to bd85ce9dee)

Solutions

Audit the pooling loop for duplicate assignment of the same enum 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 enum count; a legitimate program cannot approach 2^32 enums.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// Not applicable to BAML users. Embedders can pre-check pool size before packing:
fn enum_pool_within_u32(program: &Program) -> bool {
    program.objects.iter().filter(|o| matches!(o, Object::Enum(_))).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 enum counts below 2^32 by construction (real programs never approach this).
Deduplicate pooled enums 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::Enum` objects to local units when `units[u].enums.len()` exceeds `u32::MAX` — only reachable with an absurdly large or pathologically duplicated enum pool.

Common situations: Not hit by real BAML programs; appears in fuzzing or compiler-dev contexts such as a dedup failure pushing enums repeatedly, or synthetic inputs with billions of enum 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/bf61a554ad191711. Report an issue: GitHub.