{what} is experimental. Enable it with `mise settings experi

Error message

{what} is experimental. Enable it with `mise settings experimental=true`

What it means

mise gates experimental features behind the `experimental` setting. Settings::ensure_experimental is called before executing such a feature; if `mise settings experimental=true` is not set (and the feature is not otherwise force-enabled), mise refuses with this message telling the user exactly how to opt in.

Source

Thrown at src/config/settings.rs:1415

    /// Returns configured lockfile platforms parsed into Platform structs, or None for defaults.
    /// Errors on invalid platform strings (same validation as `mise lock --platform`).
    pub(crate) fn lockfile_platforms(&self) -> Result<Option<Vec<Platform>>> {
        match &self.lockfile_platforms {
            Some(platforms) if !platforms.is_empty() => {
                Ok(Some(Platform::parse_multiple(platforms)?))
            }
            _ => Ok(None),
        }
    }

    pub(crate) fn force_provenance_verify(&self) -> bool {
        self.locked_verify_provenance || self.paranoid
    }

    pub(crate) fn ensure_experimental(&self, what: &str) -> Result<()> {
        if !self.experimental {
            bail!("{what} is experimental. Enable it with `mise settings experimental=true`");
        }
        Ok(())
    }

    pub(crate) fn trusted_config_paths(&self) -> impl Iterator<Item = PathBuf> + '_ {
        self.trusted_config_paths
            .iter()
            .filter(|p| !p.to_string_lossy().is_empty())
            .map(file::replace_path)
            .filter_map(|p| file::canonicalize_cached(&p))
    }

    pub(crate) fn global_tools_file(&self) -> PathBuf {
        env::var_path("MISE_GLOBAL_CONFIG_FILE")
            .or_else(|| env::var_path("MISE_CONFIG_FILE"))
            .unwrap_or_else(|| {
                if self.asdf_compat {
                    env::HOME.join(&*env::MISE_DEFAULT_TOOL_VERSIONS_FILENAME)

View on GitHub (pinned to afd2eddd3a)

Solutions

Run `mise settings set experimental true` (or add `experimental = true` under [settings] in mise.toml)
Set MISE_EXPERIMENTAL=1 in the environment for CI/one-off runs
Check which feature raised the error (the {what} text) and read its docs before enabling experimental mode
If the feature is no longer experimental, upgrade mise — the gate may have been removed

Example fix

# before
mise run my-experimental-task
# Error: ... is experimental.

# after
mise settings set experimental true
mise run my-experimental-task

Defensive patterns

Strategy: validation

Validate before calling

# shell: gate before invoking a feature known to be experimental
[ "$(mise settings get experimental)" = "true" ] || mise settings set experimental true

Prevention

Check the feature's docs for an experimental notice before adopting it
Set `experimental = true` once in your global ~/.config/mise/settings.toml if you opt into experimental features
Set MISE_EXPERIMENTAL=1 in CI images that rely on experimental functionality
Re-check the flag after mise upgrades; features may graduate out of the gate

When it happens

Trigger: Using any feature that calls settings.ensure_experimental(what) — e.g. experimental backends, task features, or provenance/paranoid-adjacent functionality — while `experimental` is false in settings.

Common situations: User enables a newly announced experimental feature from docs/changelog without flipping the experimental flag; CI environment lacks the setting that a developer machine had; settings file overridden by env/CLI layers where experimental=false.

Related errors

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