manager ' ' is excluded by the system_packages.managers…

Error message

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

What it means

The manager was explicitly requested (via --manager or a `manager:package` spec) and is marked disabled because it is excluded by the `system_packages.managers` setting. Because it was explicitly asked for, mise fails loudly instead of silently skipping (unlike aggregated managers, which are just skipped with a debug log).

Solutions

Add the manager to the `system_packages.managers` setting.
Remove the setting restriction so all managers are eligible.
Drop the explicit --manager / manager:package spec and use only enabled managers.

Example fix

// before (settings.toml)
[system_packages]
managers = ["brew"]
// command: mise system install --manager apt git
// after
[system_packages]
managers = ["brew", "apt"]

Defensive patterns

Strategy: validation

Validate before calling

const enabled = /* read system_packages.managers */ ['brew'];
if (explicitManager && !enabled.includes(explicitManager)) { throw new Error(`manager '${explicitManager}' excluded by settings`); }

Try / catch

try { await run('mise system install --manager apt git') } catch (e) { if (String(e).includes('is excluded by the system_packages.managers')) { /* update settings or use an enabled manager */ } }

Prevention

Only pass --manager for managers in system_packages.managers
Avoid manager:package specs for excluded managers
Audit settings after copying configs between machines

When it happens

Trigger: During a multi-manager run, a ManagerPlan has `disabled = true` (excluded by `system_packages.managers`) AND the dispatcher was given an explicit manager selection (`d.manager.is_some()`).

Common situations: Explicitly passing `--manager apt` while settings restrict managers to something else; using `apt:package` specs when apt is not in the enabled managers list.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: 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;
        }
        if !d.dry_run {
            mp.manager.prepare_mutation(&mp.requests).await?;
        }
        let statuses = mp.manager.installed(&mp.requests).await?;
        if let Some(reason) = unavailable_package_reason(d, &statuses) {

View on GitHub (pinned to 533346cc37)