{"record":{"id":"19777e65ff4bb15b","repo":"jdx/mise","slug":"postinstall-requires-a-toml-config-file","errorCode":null,"errorMessage":"--postinstall requires a TOML config file","messagePattern":"--postinstall requires a TOML config file","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli/use.rs","lineNumber":267,"sourceCode":"            .iter()\n            .map(|target| target.tool.clone())\n            .collect::<Vec<_>>();\n        env::TOOL_ARGS.write().unwrap().clone_from(&tool_args);\n        let mut config = Config::get().await?;\n        let scope = if self.global {\n            ConfigScope::GlobalOnly\n        } else {\n            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,","sourceCodeStart":249,"sourceCodeEnd":285,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/cli/use.rs#L249-L285","documentation":"`mise use --postinstall` writes a tool target with a postinstall hook into the active config file. mise only supports persisting postinstall directives in TOML-based config files (mise.toml / .mise.toml etc.), so it throws this bail when any --postinstall target is requested while the resolved config source is not a MiseToml file (e.g. .tool-versions, or no config file at all).","triggerScenarios":"Running `mise use --postinstall <cmd> tool@version` (ToolArg.postinstall set) when `get_config_file().source()` is not ToolSource::MiseToml — e.g. the project uses .tool-versions, only a global non-TOML source resolves, or no config file exists in the current directory tree.","commonSituations":"Projects still using asdf-style .tool-versions files; users in a directory with no mise config so `mise use` would fall back to creating a non-TOML config; scripts that pass --postinstall to a `mise use` invocation pointed at legacy configs.","solutions":["Convert the project config to mise.toml (e.g. `mise use` without --postinstall first creates/uses mise.toml, or rename/migrate .tool-versions to mise.toml) and re-run with --postinstall.","Put the tool plus [tools] postinstall hook directly in mise.toml instead of using the CLI flag.","Drop --postinstall and run the install hook manually via `mise install` scripts or a task."],"exampleFix":"// before (fails: .tool-versions present)\nmise use --postinstall \"npm run prepare\" node@22\n// after\ncat > mise.toml <<'EOF'\n[tools]\nnode = \"22\"\nEOF\nmise use --postinstall \"npm run prepare\" node@22","handlingStrategy":"validation","validationCode":"if mise_use_args.contains('--postinstall') && !config_path.ends_with(\".toml\") {\n  eprintln!('--postinstall needs a mise.toml config; migrate .tool-versions first');\n}","typeGuard":null,"tryCatchPattern":"match mise_use(&args) {\n  Err(e) if e.to_string().contains(\"requires a TOML config file\") => migrate_to_mise_toml()? ,\n  r => r?,\n}","preventionTips":["Keep projects on mise.toml rather than .tool-versions before using advanced flags","Check `mise config ls` to confirm the resolved config is TOML","Avoid --postinstall in scripts targeting legacy configs"],"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"}