What causes "--postinstall requires a TOML config file" in jdx/mise?

Create/switch to a mise.toml config file in the project.

--postinstall requires a TOML config file

Error message

--postinstall requires a TOML config file

What it means

`mise use --postinstall <cmd>` must write the postinstall hook into a mise.toml file; run() bails when any tool target carries a postinstall but the resolved config file source is not a MiseToml (e.g. it's .tool-versions or another format).

Source

Thrown at src/cli/use.rs:268

            .iter()
            .map(|target| target.tool.clone())
            .collect::<Vec<_>>();
        env::TOOL_ARGS.write().unwrap().clone_from(&tool_args);
        let mut config = Config::get().await?;
        let scope = if self.global {
            ConfigScope::GlobalOnly
        } else {
            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,

View on GitHub (pinned to afd2eddd3a)

Solutions

Create/switch to a mise.toml config file in the project.
Move tool declarations from .tool-versions into mise.toml.
Run the command from a directory whose resolved config is a mise.toml, or pass -f/--file pointing at a mise.toml.

Example fix

// before
mise use --postinstall 'npm rebuild' node  # only .tool-versions exists
// after
mv .tool-versions mise.toml   # or create mise.toml
mise use --postinstall 'npm rebuild' node

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Ensure the project uses mise.toml before using --postinstall.
Avoid mixing asdf .tool-versions workflows with mise-specific flags.
Verify the resolved config format in scripts before use.

When it happens

Trigger: `mise use --postinstall 'cmd' <tool>` while get_config_file().await resolves to a non-mise.toml source (ToolSource not MiseToml), checked in run().

Common situations: Project uses .tool-versions (asdf compat); user runs from a directory where the active config is not mise.toml; asdf_compat settings active.

Related errors

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