nikivdev/code · error · anyhow::Error

bun or npm is required to install docs hub dependencies

Error message

bun or npm is required to install docs hub dependencies

What it means

ensure_docs_hub_deps requires bun or npm to install the docs hub's JavaScript dependencies. If neither executable is found on PATH (via the `which` crate), it bails rather than attempting the install, since there is no supported fallback package manager.

Source

Thrown at src/docs.rs:545

    if let Some(pid) = load_docs_hub_pid()? {
        terminate_process(pid).ok();
        remove_docs_hub_pid().ok();
    }
    kill_docs_hub_by_port(4410).ok();
    Ok(())
}

fn ensure_docs_hub_deps(hub_root: &Path) -> Result<()> {
    let node_modules = hub_root.join("node_modules");
    if node_modules.exists() {
        return Ok(());
    }
    if which("bun").is_ok() {
        run_command("bun", &["install"], hub_root)
    } else if which("npm").is_ok() {
        run_command("npm", &["install"], hub_root)
    } else {
        bail!("bun or npm is required to install docs hub dependencies");
    }
}

fn run_docs_hub_dev(hub_root: &Path, host: &str, port: u16, no_open: bool) -> Result<()> {
    let mut cmd = if which("bun").is_ok() {
        let port_arg = port.to_string();
        let host_arg = host.to_string();
        let mut cmd = Command::new("bun");
        cmd.args([
            "run",
            "dev",
            "--",
            "--port",
            &port_arg,
            "--hostname",
            &host_arg,
        ]);
        cmd

View on GitHub (pinned to a747e741ae)

Solutions

Install bun (curl -fsSL https://bun.sh/install | bash) or Node.js/npm and ensure it is on PATH
If the tool is run from a service/daemon, set PATH explicitly (e.g. PATH=/usr/local/bin:/usr/bin:...) in the unit or wrapper
If using nvm, source nvm in the shell profile or symlink node/npm into /usr/local/bin
Verify with `which bun || which npm` before invoking the hub command

Example fix

// before: shell without node tooling
$ which npm
(not found)
// after
$ curl -fsSL https://bun.sh/install | bash
$ export PATH="$HOME/.bun/bin:$PATH"
$ mytool docs hub  # bun found, deps installed

Defensive patterns

Strategy: validation

Validate before calling

use std::process::Command;
fn has(cmd: &str) -> bool { Command::new("which").arg(cmd).output().map(|o| o.status.success()).unwrap_or(false) }
if !has("bun") && !has("npm") {
    eprintln!("install bun or Node.js before running the docs hub");
    return;
}
run_docs_hub(&opts)?;

Try / catch

match ensure_docs_hub_deps(&hub_root) {
    Ok(()) => {}
    Err(e) if e.to_string().contains("bun or npm is required") => {
        eprintln!("install bun (curl -fsSL https://bun.sh/install | bash) or Node.js");
    }
    Err(e) => return Err(e),
}

Prevention

Install bun or Node.js on every machine/CI image that runs the hub
Set PATH explicitly in systemd units, cron, and CI envs so ~/.bun/bin or nvm paths are visible
Prefer system-wide installs (or symlinks in /usr/local/bin) over shell-profile-only installs for daemon contexts
Add a dependency check (`which bun || which npm`) to your bootstrap script

When it happens

Trigger: Running run_docs_hub, ensure_docs_hub_daemon_with_focus, or deploy_docs_hub on a machine without bun and without npm installed, or where neither is on the PATH of the process (e.g. launched from a daemon/systemd unit with a minimal PATH).

Common situations: Fresh CI container or server image without Node.js tooling; nvm-managed node not loaded in non-interactive shells; running the tool inside Docker with a slim base image; PATH stripped when invoked from a GUI app or cron.

Related errors

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