BoundaryML/baml · error

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

Error message

usage: baml toolchain pin <canary|nightly|version|path>
unexpected arguments: {}

What it means

`baml toolchain pin` accepts at most one extra argument: the selector. If additional arguments follow the selector (`args.len() > 2`), the `toolchain` function throws this usage error listing the unexpected arguments, because pin takes no flags or extras.

Source

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

        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)
                .ok_or_else(|| anyhow!("usage: baml toolchain uninstall <version>"))?;
            uninstall_toolchain(version)
        }

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Remove the extra arguments: `baml toolchain pin <selector>` only.
  2. If you wanted an override flag, check `baml toolchain install --help` — `--force` belongs to install, not pin.
  3. Inspect the command line in the wrapping script for stray tokens.

Example fix

# before
baml toolchain pin 0.210.0 --force

# after
baml toolchain pin 0.210.0
Defensive patterns

Strategy: validation

Validate before calling

args=(pin "$selector")
# pin accepts NO flags — never append anything after $selector
baml toolchain "${args[@]}"

Type guard

function isBarePinInvocation(args: string[]): boolean {
  return args.length === 2; // ['pin', selector] — nothing else allowed
}

Try / catch

try:
    subprocess.run(["baml", "toolchain", "pin", selector], check=True)
except subprocess.CalledProcessError as e:
    if "unexpected arguments" in e.stderr.decode():
        raise SystemExit("pin takes only a selector — move flags like --force to `install`")

Prevention

When it happens

Trigger: Running `baml toolchain pin 0.210.0 --force` or `baml toolchain pin nightly extra-arg` — anything with more than one token after `pin`.

Common situations: Users assuming `pin` supports an `--force` flag (only `install` does), copy-pasting flags from other subcommands, or accidental extra tokens in shell scripts.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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