What causes "array assignment index out of bounds" in BoundaryML/baml?

Extend the list before assigning (e.g. rebind `arr = arr + [value]` to append)

array assignment index out of bounds

Error message

array assignment index out of bounds

What it means

After confirming the index is a valid non-negative integer, the interpreter checks that the target list actually has an element at that position. BAML's array assignment does not auto-extend lists, so `idx >= items.len()` bails with `array assignment index out of bounds`.

Solutions

Extend the list before assigning (e.g. rebind `arr = arr + [value]` to append)
Assign only to indices `0..len(arr)-1`
Fix loop bounds so the index stays within the current length
Pre-populate the list to the required size before positional writes

Example fix

// before
let arr = [1, 2];
arr[2] = 3; // out of bounds
// after
let arr = [1, 2];
let arr = arr + [3]; // append

Defensive patterns

Strategy: validation

Validate before calling

// ensure the index is within the current list length
assert i < arr.len();

Type guard

fn in_bounds(len: usize, idx: usize) -> bool { idx < len }

Try / catch

// host-side
match result {
    Err(e) if e.to_string().contains("index out of bounds") => {
        // fall back to append (arr = arr + [v]) or extend first
    }
    other => other?,
}

Prevention

Append with concatenation instead of assigning past the end
Pre-size lists before positional writes
Double-check loop bounds against list length

When it happens

Trigger: `arr[i] = v` where `i` equals or exceeds the current length of the list stored in `arr`.

Common situations: Appending by assigning at `len(arr)` (Python-style `arr[len] = x`); sparse index writes; loops whose upper bound is computed incorrectly.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/19e8e6d4f1f316ec. Report an issue: GitHub.

Appendix: source

Thrown at engine/baml-compiler/src/thir/interpret.rs:1536

                        run_llm_function,
                        watch_handler,
                        function_name,
                    )
                    .await?,
                )?;

                let idx = match index_value {
                    BamlValueWithMeta::Int(i, _) if i >= 0 => i as usize,
                    _ => bail!(
                        "array assignment requires a non-negative integer index at {:?}",
                        meta.0
                    ),
                };

                match &mut base_value {
                    BamlValueWithMeta::List(items, _) => {
                        if idx >= items.len() {
                            bail!("array assignment index out of bounds");
                        }
                        items[idx] = value_to_assign.clone();
                    }
                    _ => bail!("array assignment on non-list value at {:?}", meta.0),
                }

                value_to_assign = base_value;
                current_expr = base.as_ref();
            }
            _ => return Err(anyhow!("Complex assignment targets not yet supported")),
        }
    }
}

fn lookup(scopes: &[Scope], name: &str) -> Option<BamlValueWithMeta<ExprMetadata>> {
    for s in scopes.iter().rev() {
        if let Some(cell) = s.variables.get(name) {
            return Some(cell.lock().unwrap().clone());

View on GitHub (pinned to bd85ce9dee)