{"record":{"id":"6f2226833027b268","repo":"jdx/mise","slug":"settings-name-must-resolve-to-an-absolute-path","errorCode":null,"errorMessage":"settings.{name} must resolve to an absolute path","messagePattern":"settings\\.(.+?) must resolve to an absolute path","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/config/settings.rs","lineNumber":658,"sourceCode":"        if partial.task.cache.remote_url.is_none() {\n            partial.task.cache.remote_url = Some(v);\n        }\n    }\n    partial\n}\n\nfn normalize_storage_dirs(settings: &mut Settings) -> Result<()> {\n    for (name, path) in [\n        (\"shims_dir\", &mut settings.shims_dir),\n        (\"system_installs_dir\", &mut settings.system_installs_dir),\n        (\"system_shims_dir\", &mut settings.system_shims_dir),\n    ] {\n        let Some(configured) = path.take() else {\n            continue;\n        };\n        let configured = file::replace_path(&configured);\n        if !configured.is_absolute() {\n            bail!(\"settings.{name} must resolve to an absolute path\");\n        }\n        *path = Some(configured);\n    }\n    Ok(())\n}\n\nfn strip_local_only_settings(settings: &mut toml::Table, path: &Path, is_global: bool) {\n    if is_global {\n        return;\n    }\n\n    for key in SETTINGS_META\n        .iter()\n        .filter_map(|(key, meta)| meta.global_only.then_some(*key))\n    {\n        if let Some(value) = remove_nested_toml_value(settings, key)\n            && should_warn_ignored_global_only_value(&value)\n        {","sourceCodeStart":640,"sourceCodeEnd":676,"githubUrl":"https://github.com/jdx/mise/blob/afd2eddd3a50c16190efc1c7e94404b48f72af57/src/config/settings.rs#L640-L676","documentation":"mise validates that the settings shims_dir, system_installs_dir, and system_shims_dir resolve to absolute paths after path expansion (~ substitution etc.). If a configured value for one of these settings is still relative after replace_path expansion, settings loading (load_sources_from -> normalize_storage_dirs) fails so that mise never writes shims or installs into ambiguous relative locations.","triggerScenarios":"Setting `shims_dir`, `system_installs_dir`, or `system_shims_dir` in settings (mise.toml [settings], ~/.config/mise/settings.toml, or MISE_ env overrides) to a relative path like `shims` or `./installs` that does not become absolute after ~ expansion.","commonSituations":"Users set `shims_dir = \"~/.local/shims\"` and ~ expansion fails or the value is written without ~ (e.g. `shims_dir = \"bin/shims\"`); config copied from docs where a placeholder relative path was kept; env var substitution (e.g. $SOME_VAR) resolves to empty leaving a relative fragment.","solutions":["Change the setting to an absolute path, e.g. shims_dir = \"/home/user/.local/share/mise/shims\"","Use a leading ~ (tilde) so replace_path expands it to an absolute home path","Fix any env/template variables in the value that resolve to empty or relative strings","Run `mise settings get shims_dir` (and the other two) to inspect the resolved value"],"exampleFix":"// before (settings.toml)\nshims_dir = \"bin/shims\"\n\n// after\nshims_dir = \"~/.local/share/mise/shims\"","handlingStrategy":"validation","validationCode":"# shell: before applying settings, check the three dir settings are absolute\nfor s in shims_dir system_installs_dir system_shims_dir; do\n  v=$(mise settings get \"$s\" 2>/dev/null) || continue\n  case \"$v\" in /*) ;; \\~/*) ;; *) echo \"$s must be absolute: $v\" ;; esac\ndone","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always use absolute paths or a leading ~ for shims_dir, system_installs_dir, and system_shims_dir","Avoid env/template variables in these settings that could expand to empty strings","Test settings changes with `mise settings get <name>` before committing them","Copy path examples from docs verbatim instead of hand-shortening them"],"tags":["settings","config","path","mise"],"backgroundTag":"invalid-config-value","analyzedSha":"afd2eddd3a50c16190efc1c7e94404b48f72af57","analyzedAt":"2026-09-09T01:38:25.179Z","contentChangedAt":"2026-09-09T01:38:25.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}