jdx/mise · error

{plugin_name} is not a valid plugin name

Error message

{plugin_name} is not a valid plugin name

What it means

Bailed from BackendArg::backend() (src/cli/args/backend_arg.rs:339) when the short name contains ':' (parsed as backend:tool or plugin:tool) but the prefix parses as no known BackendType and install_state::get_plugin_type() has no record of it. In other words: 'xxx:yyy' where xxx is neither a backend alias nor an installed plugin.

Source

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

                        );
                    }
                    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(", ")
                );
            }

            let registry_shorts: Vec<&str> = REGISTRY.keys().collect();
            let mut suggestions: Vec<String> =
                xx::suggest::similar_n_with_threshold(&self.short, &registry_shorts, 3, 0.8)
                    .into_iter()

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

  1. Fix the separator grammar: versions use '@' ('mise use node@20'); colons are reserved for backends/plugins
  2. Correct the prefix: valid backend prefixes include aqua:, github:, gitlab:, npm:, pipx:, gem:, cargo:, go:, dotnet:, conda:, asdf:, vfox:
  3. If a plugin was meant, install it first: 'mise plugin add <name-or-url>', then reference 'name:tool'
  4. Use the bare registry short name when it exists: 'mise registry | grep <name>'

Example fix

# before
mise use node:20   # ':' is a backend separator, not a version pin
# Error: node is not a valid plugin name

# after
mise use node@20
Defensive patterns

Strategy: validation

Validate before calling

# bash: accept only known backend prefixes or installed plugins for 'xxx:yyy' specs
prefix="${SPEC%%:*}"
case "$prefix" in
  aqua|github|gitlab|npm|pipx|gem|cargo|go|dotnet|conda|asdf|vfox) exit 0 ;;
esac
mise plugin ls 2>/dev/null | grep -qx "$prefix" || { echo "unknown backend/plugin prefix: $prefix" >&2; exit 1; }

Try / catch

# bash: surface the error and stop instead of half-running
if ! mise use "$SPEC" 2>err.log; then
  cat err.log >&2   # message names the invalid prefix explicitly
  exit 1
fi

Prevention

When it happens

Trigger: Typos in the prefix such as 'mise use aqau:owner/repo'; referencing 'plugin:tool' without ever running 'mise plugin add'; a removed plugin still named in a script or mise.toml; using ':' where '@' was meant ('mise use node:20' pins no version - it claims a backend named 'node').

Common situations: New users mixing up @ (version) and : (backend) separators; CI caches where plugins were never installed; shared mise.toml entries that depend on locally-installed plugins.

Related errors

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