manager '{only}' is excluded by the system_packages.managers

Error message

manager '{only}' is excluded by the system_packages.managers setting (currently: {})

What it means

`mise system install/update` aggregates [bootstrap.packages] entries per package manager, but managers not listed in the system_packages.managers setting are dropped during aggregation. When you explicitly pass --manager <name>, mise checks the setting directly: if the manager is not in the enabled list, it fails with this error and shows the current allow-list, so you know it is a configuration exclusion rather than a missing package.

Source

Thrown at src/cli/system/driver.rs:70

    statuses
        .iter()
        .find_map(|status| status.state.unavailable_reason())
}

/// Run `action` for every manager in `mgrs`, honoring the `--manager` filter,
/// disabled/unavailable managers, unsatisfiable version pins, and the
/// confirmation prompt.
pub(crate) async fn run(mgrs: Vec<ManagerPackages>, action: Action, d: &DriverOpts) -> Result<()> {
    if let Some(only) = &d.manager
        && !mgrs.iter().any(|mp| mp.manager.name() == only)
    {
        // distinguish "not configured" from "filtered out by settings" —
        // the aggregation drops managers excluded by
        // system_packages.managers before we ever see them
        if let Some(enabled) = &Settings::get().system_packages.managers
            && !enabled.contains(only)
        {
            bail!(
                "manager '{only}' is excluded by the system_packages.managers setting \
                 (currently: {})",
                enabled.join(", ")
            );
        }
        bail!("no packages requested for manager '{only}'");
    }
    if mgrs.is_empty() {
        info!("no bootstrap packages configured in [bootstrap.packages]");
        return Ok(());
    }
    let opts = InstallOpts {
        dry_run: d.dry_run,
        update: d.update,
    };
    for mp in mgrs {
        if let Some(only) = &d.manager
            && mp.manager.name() != only

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Add the manager to the allow-list: `mise settings set system_packages.managers brew,apt` (or edit mise.toml), then retry
Or use one of the already-enabled managers shown in the error message
Or remove the system_packages.managers restriction entirely if all managers should be usable

Example fix

# before
# settings: system_packages.managers = ["brew"]
mise system install --manager apt   # fails

# after
mise settings set system_packages.managers brew,apt
mise system install --manager apt

Defensive patterns

Strategy: validation

Validate before calling

# bash: check the manager is allowed before requesting it
enabled=$(mise settings get system_packages.managers 2>/dev/null || true)
[[ -z "$enabled" || ", $enabled, " == *", $MGR,"* ]] || { echo "$MGR excluded by settings: $enabled" >&2; exit 2; }
mise system install --manager "$MGR"

Prevention

Keep system_packages.managers consistent across the team config when scripts request specific managers
Print `mise settings get system_packages.managers` in bootstrap scripts' diagnostics on failure

When it happens

Trigger: Running `mise system install --manager apt` (or brew/etc.) when settings define `system_packages.managers = ["brew"]` (or any list not containing apt).

Common situations: Team config restricting managers to a subset (e.g. brew-only) while a developer on Linux requests apt; copying a config that whitelists one manager to a machine needing another; forgetting the setting was added globally.

Related errors

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