What causes "toolchain binary not found: {}{origin}" in BoundaryML/baml?

Verify the file exists at the given path (ls -l ) and correct typos.

toolchain binary not found: {}{origin}

Error message

toolchain binary not found: {}{origin}

What it means

verify_path_toolchain requires that a path toolchain selector exists on disk. If the given path does not exist at all, the wrapper raises this error instead of attempting to spawn a missing binary. It exists so users get a clear message about the misconfigured path rather than a confusing spawn failure.

Source

Thrown at baml_language/crates/baml/src/main.rs:926

        ));
    }
    Ok(())
}

/// Check that a path selector points at something runnable. `origin` is a
/// pre-formatted `set by ...` line, or empty when the path came straight from
/// the command line and needs no attribution.
fn verify_path_toolchain(cli: &Path, origin: &str) -> Result<()> {
    if cli.is_dir() {
        return Err(anyhow!(
            "toolchain path is a directory: {}{origin}\nPoint at the {} binary, e.g. {}",
            cli.display(),
            cli_exe_name(),
            cli.join("bin").join(cli_exe_name()).display()
        ));
    }
    if !cli.exists() {
        return Err(anyhow!(
            "toolchain binary not found: {}{origin}",
            cli.display()
        ));
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let mode = fs::metadata(cli)
            .with_context(|| format!("failed to read {}", cli.display()))?
            .permissions()
            .mode();
        if mode & 0o111 == 0 {
            return Err(anyhow!(
                "toolchain binary is not executable: {}{origin}",
                cli.display()
            ));
        }
    }

View on GitHub (pinned to bd85ce9dee)

Solutions

Verify the file exists at the given path (ls -l <path>) and correct typos.
Install the toolchain (e.g. `baml toolchain install <version>`) or point the selector at an existing binary.
Switch to a managed toolchain: `baml toolchain use <version>` to avoid maintaining raw paths.

Example fix

// before
baml --path /opt/baml/0.210.0/bin/baml --version   // binary was removed
// after
baml toolchain install 0.210.0
baml --path /opt/baml/0.210.0/bin/baml --version

Defensive patterns

Strategy: validation

Validate before calling

const p = process.env.BAML_TOOLCHAIN_PATH!;
if (!fs.existsSync(p)) throw new Error(`toolchain binary missing: ${p}; run 'baml toolchain install <version>'`);

Type guard

function toolchainBinaryExists(p: string): boolean {
  try { return fs.statSync(p).isFile(); } catch { return false; }
}

Try / catch

try {
  execFileSync('baml', ['--version']);
} catch (e) {
  if (/toolchain binary not found/.test(e.stderr?.toString() ?? '')) {
    execFileSync('baml', ['toolchain', 'install', targetVersion]);
  }
}

Prevention

Re-check env vars/config after uninstalling or moving toolchains.
Run `baml toolchain status` before relying on a path selector.
Avoid hardcoding paths in CI; use managed versions or install steps.

When it happens

Trigger: Calling print_version, exec_path_toolchain, prepare_toolchain_selector, or status_toolchain with a path selector where `!cli.exists()` — the binary was deleted, moved, or never installed.

Common situations: A cached path in a config/env var pointing at a toolchain that was uninstalled or renamed; a typo in the path; stale pins after wiping a toolchains directory; symlinks pointing at removed targets.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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