What causes "usage: baml toolchain pin " in BoundaryML/baml?

Pass a selector: `baml toolchain pin `.

usage: baml toolchain pin <canary|nightly|version|path>

Error message

usage: baml toolchain pin <canary|nightly|version|path>

What it means

`baml toolchain pin` requires a selector argument naming the toolchain to pin (`canary`, `nightly`, a version, or a path). The `toolchain` function throws this usage error when the selector argument is missing.

Source

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

            print!("{TOOLCHAIN_HELP}");
            Ok(())
        }
        Some("install") => {
            let selector = args
                .get(1)
                .ok_or_else(|| anyhow!("usage: baml toolchain install <canary|nightly|version>"))?;
            let force = args.iter().any(|arg| arg == "--force");
            install_toolchain(selector, false, manifest_base_url.as_deref(), force)
        }
        Some("use") => {
            let selector = args.get(1).ok_or_else(|| {
                anyhow!("usage: baml toolchain use <canary|nightly|version|path>")
            })?;
            use_toolchain(selector, manifest_base_url.as_deref())
        }
        Some("pin") => {
            let selector = args.get(1).ok_or_else(|| {
                anyhow!("usage: baml toolchain pin <canary|nightly|version|path>")
            })?;
            if args.len() > 2 {
                return Err(anyhow!(
                    "usage: baml toolchain pin <canary|nightly|version|path>\nunexpected arguments: {}",
                    args[2..].join(" ")
                ));
            }
            pin_toolchain(selector, manifest_base_url.as_deref())
        }
        Some("update") => update_toolchain(manifest_base_url.as_deref()),
        Some("status") => status_toolchain(manifest_base_url.as_deref()),
        Some("list") => {
            list_toolchains();
            Ok(())
        }
        Some("uninstall") => {
            let version = args
                .get(1)

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass a selector: `baml toolchain pin <canary|nightly|version|path>`.
Run `baml toolchain list` to find an installed version to pin.
Check the project manifest to confirm which toolchain version you intend to pin.

Example fix

# before
baml toolchain pin

# after
baml toolchain pin 0.210.0

Defensive patterns

Strategy: validation

Validate before calling

selector="${1:?usage: baml toolchain pin <canary|nightly|version|path>}"
baml toolchain pin "$selector"

Type guard

const hasSelector = (args: string[]): args is [string, string] =>
  args.length >= 2 && args[1].length > 0;

Try / catch

try:
    subprocess.run(["baml", "toolchain", "pin", selector], check=True)
except subprocess.CalledProcessError as e:
    if "usage: baml toolchain pin" in e.stderr.decode():
        raise SystemExit("Pin requires a selector argument")

Prevention

Pin always needs exactly one selector argument.
Verify the version string matches `baml toolchain list` output before pinning.
Script defensively with ${VAR:?} guards for all selector variables.

When it happens

Trigger: Running `baml toolchain pin` with no argument at all.

Common situations: Users forgetting which argument pin takes, scripts with empty version variables, or assuming pin reads a default toolchain when none is supplied.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

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