jdx/mise · error

{key} cannot be set in a config file: mise reads it before c

Error message

{key} cannot be set in a config file: mise reads it before config files load. Use the {} environment variable instead.

What it means

Some settings are flagged env_only in SETTINGS_META because mise reads them from the environment before any config file loads — writing them into a config would succeed on disk but be ignored at runtime, while `mise settings get` would misleadingly report the stored value. `mise settings set` therefore refuses, naming the environment variable to use instead (meta.env, falling back to a MISE_* hint). `mise settings unset` stays allowed so stale entries can be cleaned up (see discussion jdx/mise#5791).

Source

Thrown at src/cli/settings/set.rs:55

            }
        }
    }
}

pub(super) fn set(mut key: &str, value: &str, add: bool, local: bool) -> Result<()> {
    let meta = match SETTINGS_META.get(key) {
        Some(meta) => meta,
        None => {
            bail!("Unknown setting: {}", key);
        }
    };

    // Writing it would succeed and then be ignored, and `mise settings get` would report the
    // stored value as if it were live. See https://github.com/jdx/mise/discussions/5791.
    // `mise settings unset` is deliberately still allowed, so anyone who already has one of
    // these in a config can remove it.
    if meta.env_only {
        bail!(
            "{key} cannot be set in a config file: mise reads it before config files load. Use the {} environment variable instead.",
            meta.env.unwrap_or("matching MISE_*")
        );
    }

    let value = match meta.type_ {
        SettingsType::Bool => parse_bool(value)?,
        SettingsType::Integer => parse_i64(value)?,
        SettingsType::Duration => parse_duration(value)?,
        SettingsType::Url | SettingsType::Path | SettingsType::String => value.into(),
        SettingsType::ListString => parse_list_by_comma(value)?,
        SettingsType::ListPath => parse_list_by_os_path_separator(value)?,
        SettingsType::SetString => parse_set_by_comma(value)?,
        SettingsType::IndexMap => parse_indexmap_by_json(value)?,
        SettingsType::BoolOrString => parse_bool(value).unwrap_or_else(|_| value.into()),
    };

    let path = if local {

View on GitHub (pinned to 6f52dcdf99)

Solutions

1. Export the environment variable named in the error message in your shell profile (the message names the exact variable to use instead of the generic MISE_* fallback)
2. Remove any stale config entry with `mise settings unset KEY` — unset is deliberately still permitted
3. For settings that are not env-only, keep using `mise settings set` normally

Example fix

# before
mise settings set cd_tools true   # cd_tools cannot be set in a config file: mise reads it before config files load. Use the MISE_CD environment variable instead.

# after (persist in shell profile)
export MISE_CD=true

# try config first, fall back to the env var the error names
out=$(mise settings set "$k" "$v" 2>&1) || {
  case "$out" in
    *'environment variable instead'*)
      echo "note: $k is env-only; export its variable in shell profiles" >&2;;
    *) printf '%s\n' "$out" >&2; exit 1;;
  esac
}

is_env_only_setting() { mise settings set "$1" __probe__ 2>&1 | grep -q 'cannot be set in a config file'; }

Catch 'cannot be set in a config file', extract the environment variable name from the message text (it appears before 'environment variable instead'), and export that variable in the session/profile instead.

When it happens

Trigger: Running `mise settings set <env-only-key> <value>` for any setting whose metadata has env_only = true; typically settings consumed at startup like MISE_* environment variables.

Common situations: Migrating shell-exported configuration into mise.toml and hitting the one category that cannot move; following older docs that predate the env_only guard; leftover config entries from before the validation existed.

Related errors

• Setting [{}] is not set
• Unknown setting: {}
• Unknown setting: {}
• {raw}: multiple [dotfiles] edit entries match; choose one of
• No config file found in current directory

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/5871b6b29cf6ae13. Report an issue: GitHub.