{} is not available: required binary '{binary}' not found; a

Error message

{} is not available: required binary '{binary}' not found; add it to [tools] or install it manually

What it means

A package plugin declares a required binary (its hook needs an external program). checked_hook_env verifies every required binary is on PATH before running hooks, and fails early with a clear message naming the missing binary instead of letting the hook fail opaquely.

Source

Thrown at src/system/packages/plugin.rs:231

                let mut paths = Self::sync_lookup_path();
                paths.extend(toolset.list_paths(&config).await);
                let path =
                    join_paths(&paths).wrap_err("failed to construct package plugin PATH")?;
                let mut env: IndexMap<String, String> = crate::env::vars_safe().collect();
                env.insert("PATH".into(), path.to_string_lossy().into_owned());
                Ok(env)
            })
            .await
    }

    async fn checked_hook_env(&self) -> Result<&IndexMap<String, String>> {
        let env = self.hook_env().await?;
        let paths = env
            .get("PATH")
            .map(|path| split_paths(path).collect::<Vec<_>>())
            .unwrap_or_default();
        if let Some(binary) = self.missing_from_path(&paths) {
            bail!(
                "{} is not available: required binary '{binary}' not found; add it to [tools] or install it manually",
                self.name
            );
        }
        Ok(env)
    }

    fn requests(pkgs: &[PackageRequest]) -> Vec<VfoxPackageRequest> {
        pkgs.iter()
            .map(|pkg| VfoxPackageRequest {
                name: pkg.name.clone(),
                version: pkg.version.clone(),
            })
            .collect()
    }

    fn vfox(&self, env: &IndexMap<String, String>) -> Result<vfox::Vfox> {
        let (mut vfox, _) = self.plugin.vfox()?;

View on GitHub (pinned to afd2eddd3a)

Solutions

Add the required binary to the [tools] section of your mise config so mise installs it
Install the binary manually with your system package manager and ensure it is on PATH
Verify with `which <binary>` (in the same shell mise runs in) that it resolves
If the plugin declares the wrong binary name, fix or report the plugin's binary requirement

Example fix

// before (mise.toml)
[packages]
myplugin:redis-client = "*"
// error: redis-client is not available: required binary 'redis-cli' not found
// after (mise.toml)
[tools]
redis-cli = "7.4"
[packages]
myplugin:redis-client = "*"

Defensive patterns

Strategy: validation

Validate before calling

let required = plugin.required_binaries();
let missing: Vec<_> = required.iter().filter(|b| which(b).is_err()).collect();
if !missing.is_empty() { install_tools(missing)?; }

Type guard

fn binary_available(bin: &str, paths: &[PathBuf]) -> bool {
    paths.iter().any(|p| p.join(bin).is_file())
}

Try / catch

match plugin.installed(&req).await {
    Err(e) if e.to_string().contains("required binary") => {
        let bin = extract_missing_binary(&e)?; install_tool(bin).await?; retry()
    }
    other => other,
}

Prevention

Declare every system binary a plugin needs in [tools] in mise.toml
Verify binaries with `which <name>` in the same environment mise runs hooks in
In CI, pre-install plugin-required binaries in the image

When it happens

Trigger: Calling action, uninstall_action, or installed when the plugin's required binary is not found in any PATH directory of the hook environment — e.g. the binary isn't declared in [tools] and isn't installed on the system.

Common situations: Fresh machine or CI container missing the system binary the plugin depends on; binary installed via mise but shims not on PATH in the hook env; typo in the plugin's required binary name.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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