What causes "settings.{name} must resolve to an absolute path" in jdx/mise?

Change the setting to an absolute path, e.g. shims_dir = "/home/user/.local/share/mise/shims"

settings.{name} must resolve to an absolute path

Error message

settings.{name} must resolve to an absolute path

What it means

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.

Source

Thrown at src/config/settings.rs:658

        if partial.task.cache.remote_url.is_none() {
            partial.task.cache.remote_url = Some(v);
        }
    }
    partial
}

fn normalize_storage_dirs(settings: &mut Settings) -> Result<()> {
    for (name, path) in [
        ("shims_dir", &mut settings.shims_dir),
        ("system_installs_dir", &mut settings.system_installs_dir),
        ("system_shims_dir", &mut settings.system_shims_dir),
    ] {
        let Some(configured) = path.take() else {
            continue;
        };
        let configured = file::replace_path(&configured);
        if !configured.is_absolute() {
            bail!("settings.{name} must resolve to an absolute path");
        }
        *path = Some(configured);
    }
    Ok(())
}

fn strip_local_only_settings(settings: &mut toml::Table, path: &Path, is_global: bool) {
    if is_global {
        return;
    }

    for key in SETTINGS_META
        .iter()
        .filter_map(|(key, meta)| meta.global_only.then_some(*key))
    {
        if let Some(value) = remove_nested_toml_value(settings, key)
            && should_warn_ignored_global_only_value(&value)
        {

View on GitHub (pinned to afd2eddd3a)

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

Example fix

// before (settings.toml)
shims_dir = "bin/shims"

// after
shims_dir = "~/.local/share/mise/shims"

Defensive patterns

Strategy: validation

Validate before calling

# shell: before applying settings, check the three dir settings are absolute
for s in shims_dir system_installs_dir system_shims_dir; do
  v=$(mise settings get "$s" 2>/dev/null) || continue
  case "$v" in /*) ;; \~/*) ;; *) echo "$s must be absolute: $v" ;; esac
done

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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