What causes "usage: baml self-update unexpected arguments: {}" in BoundaryML/baml?

Run `baml self-update` with no additional arguments.

usage: baml self-update unexpected arguments: {}

Error message

usage: baml self-update
unexpected arguments: {}

What it means

The `baml` wrapper binary rejects any arguments passed after the `self-update` subcommand. The CLI only supports a bare `baml self-update` (optionally with a help flag), so anything else is a usage error thrown by `run` in main.rs. This guards against silently ignoring flags the self-updater does not understand.

Source

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

    if args.first().map(String::as_str) == Some("--replace") {
        args.remove(0);
        return replace_running_exe(args).map(|()| 0);
    }
    if matches!(args.first().map(String::as_str), Some("--version" | "-V")) {
        print_version();
        return Ok(0);
    }
    if args.first().map(String::as_str) == Some("toolchain") {
        args.remove(0);
        return toolchain(args).map(|()| 0);
    }
    if args.first().map(String::as_str) == Some("self-update") {
        if args.get(1).is_some_and(|arg| is_help_arg(arg)) {
            print!("{SELF_UPDATE_HELP}");
            return Ok(0);
        }
        if args.len() > 1 {
            return Err(anyhow!(
                "usage: baml self-update\nunexpected arguments: {}",
                args[1..].join(" ")
            ));
        }
        return self_update().map(|()| 0);
    }
    pass_through(args)
}

fn print_version() {
    println!("baml wrapper {}", env!("CARGO_PKG_VERSION"));
    let selector = match active_selector() {
        Ok(selector) => selector,
        Err(err) => {
            println!("baml toolchain not resolved");
            println!("{err:#}");
            return;
        }

View on GitHub (pinned to bd85ce9dee)

Solutions

Run `baml self-update` with no additional arguments.
Run `baml self-update --help` to see the supported usage.
If you need force/check behavior, check `baml --help` for a supported flag on a different subcommand.

Example fix

// before
baml self-update --force

// after
baml self-update

Defensive patterns

Strategy: validation

Validate before calling

import subprocess, sys
args = [a for a in sys.argv[1:]]
if args[:1] == ["self-update"] and len(args) > 1 and args[1] not in ("--help", "-h"):
    raise SystemExit("baml self-update takes no additional arguments")
subprocess.run(["baml"] + args, check=True)

Type guard

const isBareSelfUpdate = (args: string[]): boolean =>
  args[0] === "self-update" && (args.length === 1 || isHelpArg(args[1]));

Try / catch

try:
    subprocess.run(["baml", "self-update"], check=True, capture_output=True)
except subprocess.CalledProcessError as e:
    if "unexpected arguments" in e.stderr.decode():
        print("Retry with: baml self-update (no extra flags)")

Prevention

Never add flags to `baml self-update`; it supports no options except help.
Check `baml self-update --help` before assuming flags like --force exist.
Build CLI invocations from whitelisted argument arrays, not raw user input.

When it happens

Trigger: Running `baml self-update <anything>` where the extra argument is not a help flag (e.g. `baml self-update --force`, `baml self-update nightly`). The error lists the offending arguments via `args[1..].join(" ")`.

Common situations: Users guessing at flags like `--force` or `--check`, copy-pasting install/update commands from other tools (rustup-style `self update --dry-run`), or typos where an extra token trails the subcommand.

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/9151017ddbf691ca. Report an issue: GitHub.