asdf plugin '{plugin_name}' exists but '{tool_name}' is not

Error message

asdf plugin '{plugin_name}' exists but '{tool_name}' is not available or the plugin is not properly installed

What it means

In BackendArg::backend (src/cli/args/backend_arg.rs:325), when a backend cannot be constructed but an installed plugin with that name exists, mise reports that the plugin is present but the tool is unusable — for asdf plugins specifically, the plugin directory exists but the tool either is not provided by it or the plugin installation is broken.

Source

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

        // TODO: see above about hash key
        // let backend = self.backend.get_or_try_init(|| {
        //     if let Some(backend) = backend::get(self) {
        //         Ok(backend)
        //     } else {
        //         bail!("{self} not found in mise tool registry");
        //     }
        // })?;
        // Ok(backend.clone())
        if let Some(backend) = backend::get(self) {
            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 {

View on GitHub (pinned to afd2eddd3a)

Solutions

Reinstall the plugin: mise plugin remove <plugin> && mise plugin add <plugin> (or the asdf equivalent) to repair broken files.
Check the plugin actually provides the tool: run the plugin's list-all script or `mise ls-remote <plugin>`.
Verify the tool name spelling matches what the plugin supports.
If the plugin is stale, update it (mise plugin update <plugin>) or switch to a native/vfox backend if available.

Example fix

// before: broken asdf plugin
mise install ruby@3.2  # error
// after
mise plugin remove ruby
mise plugin add ruby
mise install ruby@3.2

Defensive patterns

Strategy: try-catch

Validate before calling

# shell: check plugin health before using the tool
mise plugin list --urls | grep -q "^${plugin}" && mise ls-remote "${plugin}" >/dev/null 2>&1 \
  || echo "plugin ${plugin} missing or broken — reinstall"

Try / catch

# shell wrapper around mise commands
if ! mise exec "${tool}@${version}" -- true 2>/dev/null; then
  case "$(mise exec "${tool}@${version}" -- true 2>&1)" in
    *"is not available or the plugin is not properly installed"*)
      mise plugin remove "${plugin}" && mise plugin add "${plugin}" ;;
  esac
fi

Prevention

Install plugins via mise (mise plugin add) rather than mixing raw asdf state.
Run mise plugin update periodically to keep plugins healthy.
Verify tool names against the plugin's supported list before pinning versions.
Migrate fully from asdf to avoid stale ~/.asdf plugin state confusing mise.

When it happens

Trigger: Running any command (install, exec, ls-remote) referencing tool_name where install_state::get_plugin_type finds an Asdf plugin for plugin_name, but Backend::get fails to build a working backend for that tool.

Common situations: asdf plugin partially installed (missing repo files or failed post-install); tool name typo so the plugin exists but doesn't list that tool; plugin was cloned but its bin/list-all script is missing or not executable; stale plugin after an asdf→mise migration.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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