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

Error message

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

What it means

When the system_packages.managers setting limits which package managers are enabled, a requested manager not in that allow-list raises this error in strict mode. src/system/mod.rs:1624 checks enabled.contains(&name) and bails when the manager is excluded, reporting the currently enabled managers.

Source

Thrown at src/system/mod.rs:1624

fn resolve_managers(
    by_mgr: IndexMap<String, Vec<PackageRequest>>,
    mut manager_options: IndexMap<String, ManagerPackageOptions>,
    strict: bool,
) -> eyre::Result<Vec<ManagerPackages>> {
    let enabled = crate::config::Settings::get()
        .system_packages
        .managers
        .clone();
    let managers = packages::all_managers()
        .into_iter()
        .map(|manager| (manager.name().to_string(), manager))
        .collect::<IndexMap<_, _>>();
    let mut out = vec![];
    for (name, requests) in by_mgr {
        let disabled = enabled.as_ref().is_some_and(|e| !e.contains(&name));
        if disabled && strict {
            bail!(
                "manager '{name}' is excluded by the system_packages.managers setting \
                 (currently: {})",
                enabled.as_deref().unwrap_or_default().join(", ")
            );
        }
        match managers.get(&name) {
            Some(manager) => out.push(ManagerPackages {
                manager: manager.clone(),
                requests,
                options: manager_options.shift_remove(&name).unwrap_or_default(),
                disabled,
            }),
            None => {
                if strict {
                    bail!(
                        "unknown bootstrap package manager '{name}' — install a package plugin: mise plugin install package:{name} <url>"
                    );
                }

View on GitHub (pinned to afd2eddd3a)

Solutions

Add the manager name to the system_packages.managers setting, e.g. managers = ["brew", "apt"]
Remove or move the offending package entries to an enabled manager
Fix the manager name spelling so it matches an enabled entry in the setting

Example fix

// before (mise.toml)
[settings]
system_packages.managers = ["brew"]
[system_packages]
apt = ["jq"]
// after
[settings]
system_packages.managers = ["brew", "apt"]
[system_packages]
apt = ["jq"]

Defensive patterns

Strategy: validation

Validate before calling

// before loading config, verify every requested manager is enabled
let enabled: Option<Vec<String>> = settings.system_packages_managers;
let requested = ["brew", "apt"]; // managers referenced in [system_packages]
if let Some(enabled) = &enabled {
    let missing: Vec<_> = requested.iter().filter(|m| !enabled.contains(m)).collect();
    if !missing.is_empty() { panic!("managers not enabled: {missing:?}"); }
}

Try / catch

match result {
    Err(e) if e.to_string().contains("excluded by the system_packages.managers setting") => {
        // fall back to skipping system_packages for this manager
    }
    r => r?,
}

Prevention

Keep the system_packages.managers list in sync with every manager used in [system_packages]
Guard platform-specific package entries with os/condition settings instead of narrowing the managers list globally
Re-run `mise config lint` (or a strict load) after editing managers settings

When it happens

Trigger: A mise.toml (strict config load) declares system_packages under a manager (e.g. apt) that is not listed in the system_packages.managers setting; any config-driven package resolution that iterates by_mgr and finds disabled && strict.

Common situations: Shared team config installed on machines where system_packages.managers was narrowed (e.g. to ["brew"]) but the config still requests apt packages; trimming the managers list for CI and forgetting to remove or guard package entries; typos in the managers setting so the manager name doesn't match.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/5b0c9a9be702bf7f. Report an issue: GitHub.