jdx/mise · error

package plugin '{plugin_name}' is not a tool backend

Error message

package plugin '{plugin_name}' is not a tool backend

What it means

Bailed from BackendArg::backend() (src/cli/args/backend_arg.rs:334) when a 'plugin:tool' spec resolves through install state to PluginType::Package. Package plugins contribute tasks/bins to mise; they do not implement the tool-version backend interface, so mise refuses to treat one as a source of installable tool versions.

Source

Thrown at src/cli/args/backend_arg.rs:334

                // This could be due to the tool not being available or plugin not properly installed
                match plugin_type {
                    PluginType::Asdf => {
                        bail!(
                            "asdf plugin '{plugin_name}' exists but '{tool_name}' is not available or the plugin is not properly installed"
                        );
                    }
                    PluginType::Vfox => {
                        bail!(
                            "vfox plugin '{plugin_name}' exists but '{tool_name}' is not available or the plugin is not properly installed"
                        );
                    }
                    PluginType::VfoxBackend => {
                        bail!(
                            "vfox-backend plugin '{plugin_name}' exists but '{tool_name}' is not available or the plugin is not properly installed"
                        );
                    }
                    PluginType::Package => {
                        bail!("package plugin '{plugin_name}' is not a tool backend");
                    }
                }
            } else {
                // Plugin doesn't exist
                bail!("{plugin_name} is not a valid plugin name");
            }
        } else {
            // Check if the tool is in the registry but has no available backends
            if let Some(rt) = REGISTRY.get(self.short.as_str())
                && rt.backends().is_empty()
                && !rt.backends.is_empty()
            {
                let all_backends: Vec<&str> = rt.backends.iter().map(|rb| rb.full).collect();
                bail!(
                    "{self} is in the mise tool registry but none of its backends ({}) are supported in the current configuration",
                    all_backends.join(", ")
                );
            }

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Request the tool from a real backend instead: 'mise use aqua:owner/repo', 'github:owner/repo', 'npm:<pkg>', 'cargo:<crate>'
2. Check what the plugin actually provides: 'mise plugin ls' plus the plugin's README (tasks, bins)
3. If a tool of that name should exist, look it up: 'mise registry <name>' and use the listed backend

Example fix

# before
mise use my-pkg:cli@1.0   # my-pkg is a package plugin
# Error: package plugin 'my-pkg' is not a tool backend

# after
mise use aqua:owner/cli@1.0

# bash: only known backends may appear before ':' in a tool spec
if [[ "$SPEC" == *:* ]]; then
  prefix="${SPEC%%:*}"
  case "$prefix" in
    aqua|github|gitlab|npm|pipx|gem|cargo|go|dotnet|conda|asdf|vfox) ;;
    *) echo "'$prefix' is not a backend; package plugins cannot install tools" >&2; exit 1 ;;
  esac
fi

When it happens

Trigger: mise use/install/upgrade with a spec like 'pkg-plugin:name' or 'pkg-plugin:name@version' where install_state::get_plugin_type() returns Package - the name was installed as a package plugin, not an asdf/vfox tool plugin.

Common situations: Installing a mise package for its tasks and then trying to 'mise use' a tool from it; assuming every installed plugin provides versions; names colliding between a package plugin and a real backend.

Related errors

• vfox-backend plugin '{plugin_name}' exists but '{tool_name}'
• {plugin_name} is not a valid plugin name
• package plugin '{}' collides with a built-in package manager
• {ba} is not installed
• install from exe

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