jdx/mise · error

--tool-option requires a TOML config file

Error message

--tool-option requires a TOML config file

What it means

`mise use --tool-option key=value tool@version` persists backend/tool options into the config file. Options can only be serialized into TOML config files, so mise bails when any --tool-option value is supplied while the resolved config source is not a ToolSource::MiseToml.

Solutions

1. Create or migrate to a mise.toml config in the project (move tool entries out of .tool-versions) and re-run `mise use --tool-option ...`.
2. Edit mise.toml directly and add the tool with its options under [tools], e.g. `[tools."node".option]`.
3. Remove --tool-option and configure the option another way (env vars or backend settings).

Example fix

// before (fails: .tool-versions)
mise use --tool-option "version=stable" python@3.12
// after
mv .tool-versions mise.toml  # or create mise.toml
mise use --tool-option "version=stable" python@3.12

if mise_use_args.contains('--tool-option') && !config_path.ends_with(".toml") {
  eprintln!('--tool-option needs a mise.toml config');
}

match mise_use(&args) {
  Err(e) if e.to_string().contains("--tool-option requires a TOML") => migrate_to_mise_toml()? ,
  r => r?,
}

When it happens

Trigger: `mise use --tool-option <key>=<val> <tool>@<ver>` where `cf.source()` is not ToolSource::MiseToml — typically because the active config is .tool-versions or no TOML config file exists.

Common situations: asdf-era projects using .tool-versions that want per-tool backend options (e.g. registry/version overrides); users running mise use in a bare directory with no config file; wrappers defaulting to .tool-versions output.

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

• collection updates require scalar or array values
• config set requires a TOML config file, but
• --postinstall requires a TOML config file
• scalar values were converted to arrays
• backend must be a string or table

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

Appendix: source

Thrown at src/cli/use.rs:275

            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,
            warn_not_in_lockfile: true,
        };
        let versions: Vec<_> = self
            .tools
            .iter()

View on GitHub (pinned to 533346cc37)