managed system files are only supported on Unix

Error message

managed system files are only supported on Unix

What it means

mise's managed system files feature ([bootstrap.files] / [bootstrap.directories] in mise.toml) applies Unix ownership semantics: chown for owner/group (uid/gid) and chmod for mode. The Windows build of validate_principals only accepts empty request lists; any file or directory request fails because owner/group principals cannot be resolved without Unix credentials. Empty tables are fine and return Ok.

Source

Thrown at src/system/managed_files.rs:802

                    resolve_group(group)?;
                }
            }
        }
    }
    Ok(())
}

#[cfg(not(unix))]
pub fn validate_principals(
    files: &[ManagedFileRequest],
    directories: &[ManagedDirectoryRequest],
    _accounts: Option<&super::accounts::AccountRequests>,
    _allow_pending_accounts: bool,
) -> Result<()> {
    if files.is_empty() && directories.is_empty() {
        return Ok(());
    }
    bail!("managed system files are only supported on Unix")
}

impl PrivilegedAction {
    fn requires_preemptive_elevation(&self) -> Result<bool> {
        match self {
            // Ownership changes normally require privilege. Avoid creating or
            // replacing a path before discovering that at set_metadata().
            Self::WriteFile {
                path,
                owner,
                group,
                replace,
                ..
            } => Ok(owner.is_some()
                || group.is_some()
                || (*replace && replacement_is_not(path, ManagedPathKind::File)?)),
            Self::CreateDirectory {
                path,

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Move [bootstrap.files]/[bootstrap.directories] entries out of the shared mise.toml into a config layer Windows never loads (e.g. a Unix-only environment config or mise.local.toml kept on Unix machines)
Remove the file/directory entries on Windows machines entirely
Keep the tables but empty on Windows - empty lists pass validation
Run the bootstrap on a Unix host (WSL, container, Linux CI runner) instead of native Windows

Example fix

# before (shared mise.toml, loaded on every OS)
[bootstrap.files]
"/etc/app/app.conf" = { content = "key=value", owner = "app", mode = "0644" }

# after: keep managed files in a Unix-only config layer
# mise.toml stays platform-neutral; entries live in a config Windows does not load
[bootstrap.files]
"/etc/app/app.conf" = { content = "key=value", owner = "app", mode = "0644" }

Defensive patterns

Strategy: validation

Validate before calling

if cfg!(not(unix)) && !(files.is_empty() && directories.is_empty()) {
    // skip managed-files handling on this platform instead of calling validate_principals
}

Type guard

fn managed_files_supported() -> bool {
    cfg!(unix)
}

Try / catch

match validate_principals(&files, &dirs, accounts, allow_pending) {
    Ok(()) => {}
    Err(e) if e.to_string().contains("managed system files are only supported on Unix") => {
        // expected on Windows: skip or warn
    }
    Err(e) => return Err(e),
}

Prevention

Keep OS-specific bootstrap resources in per-platform config layers
Gate managed-files config in CI by runner OS
Document in the repo README that managed system files are Unix-only

When it happens

Trigger: Running any code path that validates managed file/directory requests (e.g. mise bootstrap) on a Windows build while mise.toml contains non-empty [bootstrap.files] or [bootstrap.directories] tables.

Common situations: A team shares a mise.toml that manages /etc/... files; Windows teammates or Windows CI runners clone the repo and run mise bootstrap and hit the Unix-only guard immediately.

Related errors

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