jdx/mise · error

vfox-backend plugin '{plugin_name}' exists but '{tool_name}'

Error message

vfox-backend plugin '{plugin_name}' exists but '{tool_name}' is not available or the plugin is not properly installed

What it means

Bailed from BackendArg::backend() (src/cli/args/backend_arg.rs:329) when a 'plugin:tool' style short name fails to produce a backend AND install_state::get_plugin_type() still reports the prefix as PluginType::VfoxBackend. mise is saying: the plugin is registered in its install state, but its files cannot actually construct a backend for the requested tool - a broken or half-finished installation rather than an unknown name.

Source

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

            Ok(backend)
        } else if let Some((plugin_name, tool_name)) = self.short.split_once(':') {
            // Check if the plugin exists first
            if let Some(plugin_type) = install_state::get_plugin_type(plugin_name) {
                // Plugin exists, but the backend couldn't be created
                // 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();

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Cleanly reinstall: 'mise plugin rm <plugin>' (if that also fails, delete ~/.local/share/mise/plugins/<plugin> and its install-state entry) then 'mise plugin add <repo-url>'
2. Inspect the plugin directory (ls ~/.local/share/mise/plugins/<plugin>) for missing or empty plugin metadata and restore the files
3. Confirm what mise sees: 'mise plugin ls' should list the plugin; then retry the original command
4. Bypass the broken plugin with an explicit backend for the same tool, e.g. 'mise use aqua:owner/repo' or 'mise use github:owner/repo'

Example fix

# before: install state says vfox-backend, but plugin files are gone
mise use my-vfb:mytool@1.0
# Error: vfox-backend plugin 'my-vfb' exists but 'mytool' is not available or the plugin is not properly installed

# after
mise plugin rm my-vfb || rm -rf ~/.local/share/mise/plugins/my-vfb
mise plugin add https://github.com/me/my-vfb
mise use my-vfb:mytool@1.0

# bash: verify the plugin is installed and intact before using plugin:tool syntax
plugin="${SPEC%%:*}"
mise plugin ls 2>/dev/null | grep -qx "$plugin" || { echo "plugin not installed: $plugin" >&2; exit 1; }
dir="$HOME/.local/share/mise/plugins/$plugin"
[ -d "$dir" ] && [ -n "$(ls -A "$dir")" ] || { echo "plugin dir incomplete: $dir" >&2; exit 1; }

# bash: on this specific error, reinstall once and retry
if ! mise use "$SPEC" 2>err.log; then
  grep -q 'not properly installed' err.log || exit 1
  mise plugin rm "${SPEC%%:*}" && mise plugin add "$REPO" && mise use "$SPEC"
fi

When it happens

Trigger: Any command that resolves a backend for a spec like 'my-vfb:tool@1.0' (mise use/install/uninstall): backend::get() returns None while the plugin's recorded type is VfoxBackend. Concrete causes: the plugin directory under ~/.local/share/mise/plugins/<name> was deleted or truncated (missing plugin metadata) while install-state metadata still labels it, or the tool portion of the pair is not provided by that plugin.

Common situations: An interrupted 'mise plugin add' or failed update; manually rm -rf-ing a plugin directory instead of 'mise plugin rm'; copying a mise data directory to a new machine without plugin files; plugin layout changes after a mise upgrade leaving stale install state.

Related errors

• package plugin '{plugin_name}' is not a tool backend
• {plugin_name} is not a valid plugin name
• package plugin '{}' collides with a built-in package manager
• systemDependencies entry must set exactly one of bin/pkgconf
• {ba} is not installed

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