{"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":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/config/settings.rs","lineNumber":659,"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":641,"sourceCodeEnd":677,"githubUrl":"https://github.com/jdx/mise/blob/533346cc374382b41ec5ff70536252b2e96e725c/src/config/settings.rs#L641-L677","documentation":"mise normalizes certain storage directory settings (e.g. cache/data/state dirs) and requires them to be absolute. After applying ~ expansion (file::replace_path), the configured value was still relative, so mise cannot safely use it.","triggerScenarios":"During load_sources_from -> normalize_storage_dirs, a settings value for one of the storage-dir keys resolves (after file::replace_path, which only expands ~) to a relative path — e.g. settings cache_dir = \"tmp/cache\" in mise.toml or MISE_CACHE_DIR-like env relative value.","commonSituations":"Setting storage dirs to relative paths in project mise.toml (project-relative paths are not allowed for these settings), or templated values producing relative results; ~-prefixed values are fine, bare relative ones are not.","solutions":["Change the setting to an absolute path, e.g. cache_dir = \"/home/me/.cache/mise\" or \"~/.cache/mise\"","If it was set via env var, export the absolute path","Remove the setting to fall back to mise's default absolute locations"],"exampleFix":"# before\n[settings]\ncache_dir = \"tmp/cache\"\n# after\n[settings]\ncache_dir = \"~/.cache/mise\"","handlingStrategy":"validation","validationCode":"# shell: ensure storage dir settings are absolute after ~ expansion\nfor key in cache_dir data_dir state_dir; do\n  v=$(tomlq -r \".settings.$key // empty\" mise.toml)\n  if [ -n \"$v\" ]; then\n    v=${v/#\\~/$HOME}\n    case \"$v\" in /*) ;; *) echo \"settings.$key must be absolute: $v\";; esac\n  fi\ndone","typeGuard":"// Rust\nfn is_absolute_after_expansion(v: &str) -> bool {\n    file::replace_path(Path::new(v)).is_absolute()\n}","tryCatchPattern":"// Rust\nmatch config_result {\n    Ok(cfg) => use(cfg),\n    Err(e) if e.to_string().contains(\"must resolve to an absolute path\") => {\n        eprintln!(\"make the named settings path absolute (use ~ expansion if needed)\");\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Always use absolute paths or ~-prefixed paths for storage-dir settings","Never assume project-relative paths work for these settings — they only apply to config/task paths","Validate mise.toml in CI (schema check) to catch relative storage paths early"],"tags":["config","settings","path","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"533346cc374382b41ec5ff70536252b2e96e725c","analyzedAt":"2026-09-17T13:35:38.149Z","contentChangedAt":"2026-09-17T13:35:38.149Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}