{"record":{"id":"5871b6b29cf6ae13","repo":"jdx/mise","slug":"key-cannot-be-set-in-a-config-file-mise-reads-i","errorCode":null,"errorMessage":"{key} cannot be set in a config file: mise reads it before config files load. Use the {} environment variable instead.","messagePattern":"(.+?) cannot be set in a config file: mise reads it before config files load\\. Use the (.+?) environment variable instead\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/cli/settings/set.rs","lineNumber":55,"sourceCode":"            }\n        }\n    }\n}\n\npub(super) fn set(mut key: &str, value: &str, add: bool, local: bool) -> Result<()> {\n    let meta = match SETTINGS_META.get(key) {\n        Some(meta) => meta,\n        None => {\n            bail!(\"Unknown setting: {}\", key);\n        }\n    };\n\n    // Writing it would succeed and then be ignored, and `mise settings get` would report the\n    // stored value as if it were live. See https://github.com/jdx/mise/discussions/5791.\n    // `mise settings unset` is deliberately still allowed, so anyone who already has one of\n    // these in a config can remove it.\n    if meta.env_only {\n        bail!(\n            \"{key} cannot be set in a config file: mise reads it before config files load. Use the {} environment variable instead.\",\n            meta.env.unwrap_or(\"matching MISE_*\")\n        );\n    }\n\n    let value = match meta.type_ {\n        SettingsType::Bool => parse_bool(value)?,\n        SettingsType::Integer => parse_i64(value)?,\n        SettingsType::Duration => parse_duration(value)?,\n        SettingsType::Url | SettingsType::Path | SettingsType::String => value.into(),\n        SettingsType::ListString => parse_list_by_comma(value)?,\n        SettingsType::ListPath => parse_list_by_os_path_separator(value)?,\n        SettingsType::SetString => parse_set_by_comma(value)?,\n        SettingsType::IndexMap => parse_indexmap_by_json(value)?,\n        SettingsType::BoolOrString => parse_bool(value).unwrap_or_else(|_| value.into()),\n    };\n\n    let path = if local {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/jdx/mise/blob/6f52dcdf99e282ef7a7db68c81301fa4618d0f79/src/cli/settings/set.rs#L37-L73","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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)","Remove any stale config entry with `mise settings unset KEY` — unset is deliberately still permitted","For settings that are not env-only, keep using `mise settings set` normally"],"exampleFix":"# before\nmise 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.\n\n# after (persist in shell profile)\nexport MISE_CD=true","handlingStrategy":"validation","validationCode":"# try config first, fall back to the env var the error names\nout=$(mise settings set \"$k\" \"$v\" 2>&1) || {\n  case \"$out\" in\n    *'environment variable instead'*)\n      echo \"note: $k is env-only; export its variable in shell profiles\" >&2;;\n    *) printf '%s\\n' \"$out\" >&2; exit 1;;\n  esac\n}","typeGuard":"is_env_only_setting() { mise settings set \"$1\" __probe__ 2>&1 | grep -q 'cannot be set in a config file'; }","tryCatchPattern":"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.","preventionTips":["Keep startup-read settings as exported env vars in shell profiles, not in mise.toml","Use `mise settings unset` to clean up stale env-only entries — it stays allowed by design","Watch for the env_only category when migrating shell config into mise config files"],"tags":["settings","env-var","config","startup-order","mise"],"backgroundTag":"env-only-setting","analyzedSha":"6f52dcdf99e282ef7a7db68c81301fa4618d0f79","analyzedAt":"2026-08-22T10:14:23.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T20:17:18.057Z"}