jdx/mise · error

refusing to manage the filesystem root

Error message

refusing to manage the filesystem root

What it means

After absolutizing the target, validate_privileged_target refuses the exact path "/". Managing the filesystem root would mean chowning/chmodding root itself and cascading over everything, so mise hard-stops. Only the canonical root path is refused; any deeper path is allowed.

Source

Thrown at src/system/managed_files.rs:1198

            Self::Symlink
        } else {
            Self::Other
        }
    }
}

fn absolute_target(path: &str) -> Result<PathBuf> {
    let path = crate::file::replace_path(Path::new(path));
    validate_privileged_target(&path)
}

fn validate_privileged_target(path: &Path) -> Result<PathBuf> {
    if !path.is_absolute() {
        bail!("managed system path must be absolute: {}", path.display());
    }
    let path = path.absolutize()?.to_path_buf();
    if path == Path::new("/") {
        bail!("refusing to manage the filesystem root");
    }
    Ok(path)
}

fn parse_mode(mode: Option<&str>, default: u32) -> Result<u32> {
    let Some(mode) = mode else {
        return Ok(default);
    };
    let mode = mode.strip_prefix("0o").unwrap_or(mode);
    let parsed = u32::from_str_radix(mode, 8).wrap_err("mode must be an octal string")?;
    if parsed > 0o7777 {
        bail!("mode must be between 0000 and 7777");
    }
    Ok(parsed)
}

fn nonempty(field: &str, value: Option<String>) -> Result<Option<String>> {
    match value {

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Point the entry at a real target under root, e.g. "/opt/app"
2. If a template produced "/", fix the variable (empty suffix, missing path join) and regenerate

Example fix

# before
[bootstrap.directories]
"/" = { mode = "0755" }

# after
[bootstrap.directories]
"/opt/app" = { owner = "app", mode = "0755" }

use path_absolutize::Absolutize;
if let Ok(canon) = std::path::Path::new(key).absolutize() {
    if canon == std::path::Path::new("/") {
        return Err(eyre::eyre!("refusing to manage the filesystem root"));
    }
}

fn is_manageable_target(p: &std::path::Path) -> bool {
    p.is_absolute() && p != std::path::Path::new("/")
}

When it happens

Trigger: A [bootstrap.files] or [bootstrap.directories] entry whose key is "/" or normalizes to it (e.g. "/..").

Common situations: A templating loop or variable renders an empty/root path into the config; hand-edited typo; generated config not reviewed before bootstrap.

Related errors

• managed system path must be absolute: {}
• managed file parent is not a directory: {}
• path "{path_raw}" must be absolute or start with ~/, ignorin
• mode must be between 0000 and 7777
• {field} must not be empty

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/73ab44503d3f6d1a. Report an issue: GitHub.