jdx/mise · error

bootstrap users and groups are only supported on Linux

Error message

bootstrap users and groups are only supported on Linux

What it means

mise's bootstrap account provisioning (users and groups defined in [bootstrap] config) is implemented with nix and Linux account APIs, so it only supports Linux. The code checks cfg!(target_os = "linux") before processing any configured accounts and bails with this error on any other platform (macOS, Windows, BSDs). It is a hard guard, not a fallback: configuration is parsed first, then rejected at runtime if accounts are requested.

Solutions

1. Remove the [bootstrap.groups] and [bootstrap.users] sections from your mise.toml on non-Linux machines (e.g. keep them only in a Linux-specific environment config file)
2. Guard the account config with an os-specific condition or move it to a config file loaded only on Linux hosts
3. Provision the users/groups outside mise (systemd-sysusers, Ansible, Dockerfile USER/groupadd) and drop the bootstrap section
4. Run the task on a Linux host/container instead

Example fix

# before (mise.toml, fails on macOS)
[bootstrap.groups]
app = { gid = 1500 }
[bootstrap.users]
app = { group = "app", system = true }

# after (moved to a Linux-only config, e.g. mise.linux.toml, or removed on macOS)

# shell check before committing a shared config
if [ "$(uname -s)" != "Linux" ] && grep -q '^\[bootstrap\.' mise.toml; then
  echo "bootstrap accounts are Linux-only; use a Linux-specific config" >&2
fi

When it happens

Trigger: Running mise on a non-Linux OS (macOS/Windows) with a mise.toml that defines any bootstrap users or groups; CI/devcontainer images on non-Linux runners that share a config with Linux hosts; macOS users who copy a colleague's config containing [bootstrap.groups]/[bootstrap.users].

Common situations: Teams with mixed macOS/Linux workstations sharing one repo-level mise.toml; Windows developers pulling a config authored for Linux containers; switching OSes and forgetting that bootstrap config is platform-specific.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• bootstrap users and groups are only supported on Linux
• [bootstrap].config_roots did not match any config roots
• bootstrap resource ' ' depends on missing resource
• bootstrap resource ' ' is declared more than once
• brew-cask: : only font-only casks without lifecycle hooks…

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/d7b448768b96db6e. Report an issue: GitHub.

Appendix: source

Thrown at src/system/accounts.rs:180

pub(crate) fn requests_from_config(config: &Config) -> Result<AccountRequests> {
    let mut groups = IndexMap::new();
    let mut users = IndexMap::new();
    for cf in config.config_files.values() {
        if let Some(bootstrap) = cf.bootstrap_config() {
            for (name, group) in bootstrap.groups {
                groups.entry(name).or_insert(group);
            }
            for (name, user) in bootstrap.users {
                users.entry(name).or_insert(user);
            }
        }
    }
    if groups.is_empty() && users.is_empty() {
        return Ok(AccountRequests::default());
    }
    if !cfg!(target_os = "linux") {
        bail!("bootstrap users and groups are only supported on Linux");
    }
    let groups = groups
        .into_iter()
        .map(|(name, config)| GroupRequest::from_toml(name, config))
        .collect::<Result<Vec<_>>>()?;
    let users = users
        .into_iter()
        .map(|(name, config)| UserRequest::from_toml(name, config))
        .collect::<Result<Vec<_>>>()?;
    validate_requests(&groups, &users)?;
    Ok(AccountRequests { groups, users })
}

pub(crate) fn prepare_requests_from_config(config: &Config) -> Result<AccountRequests> {
    requests_from_config(config)
}

impl GroupRequest {

View on GitHub (pinned to 533346cc37)