jdx/mise · error

--tool-option requires a TOML config file

Error message

--tool-option requires a TOML config file

What it means

Config-file-type validation in `mise use` run(): --tool-option (like --postinstall) was supplied while the target config file is not a mise.toml-format TOML file (e.g. .tool-versions), which cannot represent tool option tables. The bail stops the write before corrupting an unsupported format.

Source

Thrown at src/cli/use.rs:276

            ConfigScope::All
        };
        let mut ts = ToolsetBuilder::new()
            .with_scope(scope)
            .build(&config)
            .await?;
        let mut cf = self.get_config_file().await?;
        if self.tools.iter().any(|target| target.postinstall.is_some())
            && !matches!(cf.source(), ToolSource::MiseToml(_))
        {
            bail!("--postinstall requires a TOML config file");
        }
        if self
            .tools
            .iter()
            .any(|target| !target.tool_option.is_empty())
            && !matches!(cf.source(), ToolSource::MiseToml(_))
        {
            bail!("--tool-option requires a TOML config file");
        }
        let pin = self.pin || !self.fuzzy && (Settings::get().pin || Settings::get().asdf_compat);
        let mut resolve_options = ResolveOptions {
            latest_versions: false,
            use_locked_version: true,
            resolve_rolling_channels: false,
            prefer_exact_version: pin,
            before_date: self.get_before_date()?,
            before_date_from_default: false,
            filter_installed_versions_by_release_date: false,
            offline: false,
            refresh_remote_versions: false,
            inactive: false,
        };
        let versions: Vec<_> = self
            .tools
            .iter()
            .map(|target| {

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Ensure a mise.toml exists in the project before running `mise use --tool-option`.
2. Migrate .tool-versions entries into mise.toml.
3. Pass -f/--file targeting a mise.toml explicitly.

Example fix

// before
mise use node --tool-option version=22   # config resolves to .tool-versions
// after
touch mise.toml
mise use node --tool-option version=22

[ -f mise.toml ] || { echo 'mise.toml required for --tool-option'; exit 1; }

When it happens

Trigger: `mise use <tool> --tool-option k=v` where get_config_file().await resolves to a non-mise.toml source (e.g. .tool-versions), checked in run().

Common situations: asdf-compat projects using .tool-versions; running in a directory without mise.toml; CI scripts assuming TOML output.

Related errors

• --tool-option requires a non-empty key
• tool option {key:?} was specified more than once for {}
• cannot combine {flag} with an inline {key} option for {}
• --postinstall requires a TOML config file
• {}@{requested} is not installed{resolved} hint: run `mise in

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