BoundaryML/baml · error

unknown toolchain command {other:?} {TOOLCHAIN_HELP}

Error message

unknown toolchain command {other:?}

{TOOLCHAIN_HELP}

What it means

The `toolchain` subcommand dispatcher handles install/use/pin/uninstall/list (and help); any other word after `baml toolchain` hits the `Some(other)` catch-all arm and throws this error, echoing the unknown command plus the full toolchain help text.

Source

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

                    "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)
        }
        Some(other) => Err(anyhow!(
            "unknown toolchain command {other:?}\n\n{TOOLCHAIN_HELP}"
        )),
    }
}

fn is_help_arg(arg: &str) -> bool {
    matches!(arg, "--help" | "-h" | "help")
}

fn parse_manifest_base_url(mut args: Vec<String>) -> Result<(Vec<String>, Option<String>)> {
    let mut manifest_base_url = None;
    let mut i = 0;
    while i < args.len() {
        if args[i] == "--manifest-base-url" {
            let value = args
                .get(i + 1)
                .ok_or_else(|| anyhow!("--manifest-base-url requires a value"))?
                .trim_end_matches('/')

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Read the TOOLCHAIN_HELP text printed with the error and pick a supported command.
  2. Use `baml toolchain install <selector>` to get a newer toolchain instead of a hypothetical `update`.
  3. Use `baml toolchain list` to verify the command works and see what's available.

Example fix

# before
baml toolchain update

# after
baml toolchain install nightly
Defensive patterns

Strategy: validation

Validate before calling

ALLOWED="install use pin uninstall list help"
if [[ " $ALLOWED " != *" $TOOLCHAIN_CMD "* ]]; then
  echo "unknown toolchain command: $TOOLCHAIN_CMD" >&2; exit 1
fi
baml toolchain "$TOOLCHAIN_CMD"

Type guard

const TOOLCHAIN_COMMANDS = ["install", "use", "pin", "uninstall", "list", "help"] as const;
type ToolchainCommand = typeof TOOLCHAIN_COMMANDS[number];
const isToolchainCommand = (s: string): s is ToolchainCommand =>
  (TOOLCHAIN_COMMANDS as readonly string[]).includes(s);

Try / catch

try:
    subprocess.run(["baml", "toolchain", cmd], check=True)
except subprocess.CalledProcessError as e:
    if "unknown toolchain command" in e.stderr.decode():
        raise SystemExit("Unsupported command — see TOOLCHAIN_HELP in the error output")

Prevention

When it happens

Trigger: Running `baml toolchain <typo>` where the token is not install/use/pin/uninstall/list/help — e.g. `baml toolchain update`, `baml toolchain rm`, `baml toolchain switch`.

Common situations: Muscle-memory from rustup (`rustup toolchain update`), typos like `instal`, or guessing subcommand names instead of reading help.

Related errors

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