{"record":{"id":"d963f2c3ca968a23","repo":"jdx/mise","slug":"tool-option-requires-a-toml-config-file","errorCode":null,"errorMessage":"--tool-option requires a TOML config file","messagePattern":"--tool-option requires a TOML config file","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli/use.rs","lineNumber":275,"sourceCode":"            ConfigScope::All\n        };\n        let mut ts = ToolsetBuilder::new()\n            .with_scope(scope)\n            .build(&config)\n            .await?;\n        let mut cf = self.get_config_file().await?;\n        if self.tools.iter().any(|target| target.postinstall.is_some())\n            && !matches!(cf.source(), ToolSource::MiseToml(_))\n        {\n            bail!(\"--postinstall requires a TOML config file\");\n        }\n        if self\n            .tools\n            .iter()\n            .any(|target| !target.tool_option.is_empty())\n            && !matches!(cf.source(), ToolSource::MiseToml(_))\n        {\n            bail!(\"--tool-option requires a TOML config file\");\n        }\n        let pin = self.pin || !self.fuzzy && (Settings::get().pin || Settings::get().asdf_compat);\n        let mut resolve_options = ResolveOptions {\n            latest_versions: false,\n            use_locked_version: true,\n            resolve_rolling_channels: false,\n            prefer_exact_version: pin,\n            before_date: self.get_before_date()?,\n            before_date_from_default: false,\n            filter_installed_versions_by_release_date: false,\n            offline: false,\n            refresh_remote_versions: false,\n            inactive: false,\n            warn_not_in_lockfile: true,\n        };\n        let versions: Vec<_> = self\n            .tools\n            .iter()","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/cli/use.rs#L257-L293","documentation":"`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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["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 ...`.","Edit mise.toml directly and add the tool with its options under [tools], e.g. `[tools.\"node\".option]`.","Remove --tool-option and configure the option another way (env vars or backend settings)."],"exampleFix":"// before (fails: .tool-versions)\nmise use --tool-option \"version=stable\" python@3.12\n// after\nmv .tool-versions mise.toml  # or create mise.toml\nmise use --tool-option \"version=stable\" python@3.12","handlingStrategy":"validation","validationCode":"if mise_use_args.contains('--tool-option') && !config_path.ends_with(\".toml\") {\n  eprintln!('--tool-option needs a mise.toml config');\n}","typeGuard":null,"tryCatchPattern":"match mise_use(&args) {\n  Err(e) if e.to_string().contains(\"--tool-option requires a TOML\") => migrate_to_mise_toml()? ,\n  r => r?,\n}","preventionTips":["Migrate .tool-versions to mise.toml once per project","Put tool options directly in [tools] TOML sections instead of CLI flags","Verify config source with `mise config ls` before scripting mise use"],"tags":["cli","config","toml"],"backgroundTag":"invalid-cli-argument","analyzedSha":"533346cc374382b41ec5ff70536252b2e96e725c","analyzedAt":"2026-09-17T13:35:38.149Z","contentChangedAt":"2026-09-17T13:35:38.149Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}