What causes "failed to read value segment {}: {error}" in BoundaryML/baml?

Check the preserved io::ErrorKind (e.g. PermissionDenied vs NotFound) and address that condition.

BoundaryML/baml · error · io::Error

failed to read value segment {}: {error}

Error message

failed to read value segment {}: {error}

What it means

read_value_segments reads each .bamlvalue segment file with std::fs::read; any I/O failure is wrapped in an io::Error preserving the OS error kind, with a message naming the failed path and underlying error. It indicates a value segment file exists in the listing but cannot be read.

Source

Thrown at baml_language/crates/bex_events/src/history/mod.rs:356

}

#[cfg(not(target_arch = "wasm32"))]
fn open_boundary_from_dir(dir: &Path) -> io::Result<Run> {
    open_boundary_from_segments(&read_value_segments(dir)?, Some(dir))
}

#[cfg(not(target_arch = "wasm32"))]
fn read_value_segments(dir: &Path) -> io::Result<Vec<HistoryValueSegment>> {
    value_segment_paths(dir)
        .into_iter()
        .map(|path| {
            std::fs::read(&path)
                .map(|bytes| HistoryValueSegment {
                    label: path.display().to_string(),
                    bytes,
                })
                .map_err(|error| {
                    io::Error::new(
                        error.kind(),
                        format!("failed to read value segment {}: {error}", path.display()),
                    )
                })
        })
        .collect()
}

pub fn open_boundary_from_value_segments(
    value_segments: &[HistoryValueSegment],
) -> io::Result<Run> {
    open_boundary_from_segments(value_segments, None)
}

fn open_boundary_from_segments(
    value_segments: &[HistoryValueSegment],
    fallback_dir: Option<&Path>,
) -> io::Result<Run> {

View on GitHub (pinned to bd85ce9dee)

Solutions

Check the preserved io::ErrorKind (e.g. PermissionDenied vs NotFound) and address that condition.
Re-run the recording session to regenerate complete, consistent segment files.
Avoid deleting history files concurrently with replay.
Verify filesystem permissions on the boundary directory.

Example fix

// before
let segs = read_value_segments(&dir)?;
// after
let segs = match read_value_segments(&dir) {
    Ok(s) => s,
    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
        eprintln!("segment vanished mid-replay, restarting");
        return restart_replay();
    }
    Err(e) => return Err(e),
};

Defensive patterns

Strategy: retry

Validate before calling

for p in segment_paths {
    let meta = std::fs::metadata(&p)
        .map_err(|e| format!("segment {} unreadable: {e}", p.display()))?;
    if meta.len() == 0 { return Err(format!("segment {} empty", p.display())); }
}

Try / catch

let segs = loop {
    match read_value_segments(&dir) {
        Ok(s) => break s,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound && tries < 3 => { tries += 1; continue; }
        Err(e) => return Err(e),
    }
};

Prevention

Never clean up history files concurrently with replay.
Grant the replaying process read access to the boundary directory.
Retry transient NotFound/Permission errors; regenerate artifacts for permanent ones.

When it happens

Trigger: Boundary directory contains a .bamlvalue file that is unreadable: deleted between listing and read, permission-restricted, or a hardware/OS read error.

Common situations: Concurrent cleanup deleting segments while replay reads them; running replay as a user without read permission; truncated files on a failing disk.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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