jdx/mise · error · eyre::Report

backend {backend_type} is disabled by disable_backends

Error message

backend {backend_type} is disabled by disable_backends

What it means

mise allows disabling whole backend families via the `disable_backends` setting (e.g. `["asdf", "vfox"]`). ensure_backend_enabled() checks the backend's disable_key against that list; any install/resolve operation on a tool whose backend is listed fails immediately with this error.

Source

Thrown at src/backend/mod.rs:584

pub(crate) fn remove(short: &str) {
    let mut tools = TOOLS.lock().unwrap();
    if let Some(current) = tools.as_ref() {
        let mut tools_ = current.deref().clone();
        tools_.remove(short);
        *tools = Some(Arc::new(tools_));
    }
}

pub(crate) fn is_disabled_backend_type(backend_type: &BackendType) -> bool {
    backend_type
        .disable_key()
        .is_some_and(is_disabled_backend_name)
}

pub(crate) fn ensure_backend_enabled(backend_type: &BackendType) -> Result<()> {
    if is_disabled_backend_type(backend_type) {
        bail!("backend {backend_type} is disabled by disable_backends");
    }
    Ok(())
}

fn is_disabled_backend_name(backend: &str) -> bool {
    Settings::get()
        .disable_backends
        .iter()
        .any(|disabled| disabled == backend)
}

pub(crate) fn arg_to_backend(ba: BackendArg) -> Option<ABackend> {
    match ba.backend_type() {
        BackendType::Core => {
            CORE_PLUGINS
                .get(&ba.short)
                .or_else(|| {
                    // this can happen if something like "corenode" is aliased to "core:node"

View on GitHub (pinned to 6f52dcdf99)

Solutions

1. Remove the backend from `disable_backends` (mise settings set disable_backends '[...]')
2. Migrate the offending tool to an enabled backend (aqua:/github:/cargo: equivalents usually exist)
3. Delete the tool entry that needs the disabled backend if it is no longer required

Example fix

# before
# ~/.config/mise/settings.toml: disable_backends = ["asdf"]
mise install asdf:olang   # fails
# after
disable_backends = []
mise install asdf:olang

# before installing, confirm no requested tool needs a disabled backend
mise settings get disable_backends

When it happens

Trigger: Settings (settings.toml, MISE_DISABLE_BACKENDS env, or config) contain a backend key in `disable_backends`, and a mise.toml / CLI request references a tool using that backend — e.g. `disable_backends = ["asdf"]` plus `mise use asdf:some-plugin`.

Common situations: Disabling asdf/vfox globally for security or speed, then cloning a project whose mise.toml still pins an asdf plugin; team config drift where one member disables a backend others rely on; CI images shipping restrictive settings.

Related errors

• remote cache blob packs require a positive max_pack_bytes li
• remote cache URL must use HTTPS
• remote cache URL must use HTTPS except for loopback developm
• conflicting aqua var `{key}`: use only one spelling
• locked mode requires lockfile to be enabled hint: Remove `lo

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/a0c229dfdb9a3238. Report an issue: GitHub.