jdx/mise · error

--tool-option requires a non-empty key

Error message

--tool-option requires a non-empty key

What it means

`mise use --tool-option` expects each option in KEY=VALUE form with a non-empty key; request_options() rejects options whose key is empty after trimming. This guards the tool-options TOML map from empty keys.

Source

Thrown at src/cli/use.rs:199

    }

    fn request_options(&self) -> Result<ToolVersionOptions> {
        let mut options = ToolVersionOptions::default();
        let mut entries = Vec::new();
        if let Some(command) = &self.postinstall {
            entries.push((
                "postinstall".to_string(),
                toml::Value::String(command.clone()),
                "--postinstall",
            ));
        }
        for option in &self.tool_option {
            let (key, value) = option
                .split_once('=')
                .ok_or_else(|| eyre!("--tool-option expects KEY=VALUE: {option}"))?;
            let key = key.trim();
            if key.is_empty() {
                bail!("--tool-option requires a non-empty key");
            }
            let value = toml::from_str::<toml::Table>(&format!("value = {value}"))
                .ok()
                .filter(|table| table.len() == 1)
                .and_then(|mut table| table.remove("value"))
                .unwrap_or_else(|| toml::Value::String(value.to_string()));
            entries.push((key.to_string(), value, "--tool-option"));
        }
        let mut seen = std::collections::HashSet::new();
        for (key, value, flag) in entries {
            if !seen.insert(key.clone()) {
                bail!(
                    "tool option {key:?} was specified more than once for {}",
                    self.tool
                );
            }
            if self
                .tool

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Provide a non-empty key: `--tool-option key=value`.
2. Check the variable that supplies the key in scripts.
3. Quote the argument properly in shell to avoid splitting.

Example fix

// before
mise use --tool-option '=true' node
// after
mise use --tool-option 'version=true' node

case "$opt" in *=*) key="${opt%%=*}"; [ -n "${key//[[:space:]]/}" ] || exit 1 ;; *) exit 1 ;; esac

When it happens

Trigger: Passing `--tool-option '=value'` or `--tool-option ' =value'` (key empty before/after trim) to `mise use`, in request_options().

Common situations: Shell quoting mishaps leaving an empty key; scripting loops that build --tool-option strings from empty variable names; copy-paste errors.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• --install takes the executable's name, not a tool id; run `m
• --name-only cannot be used with --json, --extended, or --usa
• task list options cannot be used with subcommands
• task list options cannot be used with task info
• tool option {key:?} was specified more than once for {}

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/67dd16868fb180a7. Report an issue: GitHub.