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

Error message

manager '{name}' is excluded by the system_packages.managers setting

What it means

During iteration over aggregated managers, an entry flagged disabled (excluded by system_packages.managers) is normally skipped with only a debug log. But because --manager was supplied, the user explicitly requested that manager, and silently skipping would make the command appear to succeed while doing nothing — so mise escalates the skip to a hard error.

Source

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

    }
    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
        {
            continue;
        }
        let name = mp.manager.name();
        if mp.disabled {
            if d.manager.is_some() {
                bail!("manager '{name}' is excluded by the system_packages.managers setting");
            }
            debug!("{name}: skipping, excluded by system_packages.managers");
            continue;
        }
        if let Some(reason) = mp.manager.unavailable_reason_async().await {
            if unavailable_manager_is_error(d) {
                // explicitly requested (via --manager or manager:package
                // specs) — failing silently would be a lie
                bail!("{name} is not available: {}", reason);
            }
            debug!("{name}: skipping, {reason}");
            continue;
        }
        let statuses = mp.manager.installed(&mp.requests).await?;
        if let Some(reason) = unavailable_package_reason(d, &statuses) {
            bail!("{reason}");
        }
        let mut targets: Vec<_> = statuses

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Include the manager in system_packages.managers (via `mise settings set` or mise.toml) and retry
Or switch to a manager that the setting allows
Or remove the system_packages.managers restriction so nothing is disabled

Example fix

# before
# settings: system_packages.managers = ["brew"]
mise system install --manager apt   # fails: apt has packages but is disabled

# after
mise settings set system_packages.managers brew,apt

Defensive patterns

Strategy: validation

Validate before calling

# bash: same guard as the aggregation check — confirm manager is enabled first
enabled=$(mise settings get system_packages.managers 2>/dev/null || true)
[[ -z "$enabled" || ", $enabled, " == *", $MGR,"* ]] || { echo "$MGR excluded: $enabled" >&2; exit 2; }
mise system install --manager "$MGR"

Prevention

Treat --manager as an explicit contract: the manager must be both configured (packages) and allowed (settings)
Audit shared configs after anyone edits system_packages.managers

When it happens

Trigger: Running `mise system install --manager <name>` where <name> IS present in mgrs (has bootstrap packages) but its ManagerPackages.disabled flag is true because system_packages.managers does not include it.

Common situations: Same shape as the aggregation-time exclusion, but hit on a manager that has packages configured; config whitelists brew while CI on Linux explicitly asks for apt which is disabled; disabling a manager globally then forgetting to re-enable before scripting against it.

Related errors

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