hive not found on PATH. Install from https://github.com/exam

Error message

hive not found on PATH. Install from https://github.com/example/hive

What it means

`run_agent` launches an external `hive` CLI in agent mode (`hive agent <agent> <prompt>`). Before doing so it probes `PATH` with the `which` crate; if `hive` isn't found it bails with this message, which includes the (placeholder) install URL. The error occurs before any subprocess is spawned.

Source

Thrown at src/hive.rs:311

                    spec_path: None,
                    config: AgentConfig {
                        name,
                        description: spec.job.or(spec.prompt),
                        ..Default::default()
                    },
                });
            }
        }
    }

    agents
}

/// Run a hive agent with a prompt
pub fn run_agent(agent: &str, prompt: &str) -> Result<()> {
    // Check if hive is available
    if which::which("hive").is_err() {
        anyhow::bail!("hive not found on PATH. Install from https://github.com/example/hive");
    }

    let status = Command::new("hive")
        .arg("agent")
        .arg(agent)
        .arg(prompt)
        .stdin(Stdio::inherit())
        .stdout(Stdio::inherit())
        .stderr(Stdio::inherit())
        .status()
        .context("Failed to run hive")?;

    if !status.success() {
        anyhow::bail!(
            "hive agent '{}' exited with status {:?}",
            agent,
            status.code()
        );

View on GitHub (pinned to a747e741ae)

Solutions

Install hive per the URL in the message, then verify with `which hive`
If already installed, add its directory to PATH: `export PATH="$PATH:/path/to/hive/bin"`
Run in an environment that inherits your PATH (avoid bare `env -i`, check cron/CI PATH)
Confirm the binary name is exactly `hive` (create a symlink if installed under another name)

Example fix

// before (call without checking)
hive::run_agent("reviewer", "review this PR")?;
// after
if which::which("hive").is_err() {
    eprintln!("hive missing; skipping agent step");
    return Ok(()); // or install hint
}
hive::run_agent("reviewer", "review this PR")?;

Defensive patterns

Strategy: validation

Validate before calling

if which::which("hive").is_err() {
    eprintln!("hive is required but not on PATH. Install it first.");
    std::process::exit(127);
}

Type guard

fn hive_available() -> bool {
    which::which("hive").is_ok()
}

Try / catch

match hive::run_agent(agent, prompt) {
    Err(e) if e.to_string().contains("hive not found") => {
        eprintln!("skipping agent step: install hive from the linked URL");
        // degrade or abort depending on whether the agent step is mandatory
    }
    r => r?,
}

Prevention

Install hive as part of machine/bootstrap setup and verify with `which hive`
Keep PATH intact in CI and cron (avoid `env -i`; export PATH explicitly)
Add a preflight dependency check at CLI startup for all external tools
Document required externals and their install URLs in the README

When it happens

Trigger: Calling `run_agent` on a machine where no `hive` executable is on PATH; running inside an environment with a stripped PATH (cron, CI containers); hive installed under a non-PATH directory.

Common situations: Fresh dev machine without hive installed; Docker image missing the hive dependency; virtualenv/conda/nix shell that shadows or omits PATH entries; typo in install location so the binary is named differently.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/28c83c097fc2c4bf. Report an issue: GitHub.