external CLI {} exited unsuccessfully with status {}

Error message

external CLI {} exited unsuccessfully with status {}

What it means

`ensure_success` converts a non-zero (or signal-killed) exit status of a spawned external CLI into a library error. The CLI itself ran and reported failure; this error just propagates its exit status with the tool id for context.

Source

Thrown at src/external_cli.rs:296

    if let Some(env_map) = &tool.manifest.exec.env {
        if env_map.is_empty() {
            println!("env: none");
        } else {
            let mut keys = env_map.keys().cloned().collect::<Vec<_>>();
            keys.sort();
            println!("env: {}", keys.join(", "));
        }
    } else {
        println!("env: none");
    }
    Ok(())
}

fn ensure_success(id: &str, status: ExitStatus) -> Result<()> {
    if status.success() {
        Ok(())
    } else {
        bail!(
            "external CLI {} exited unsuccessfully with status {}",
            id,
            status
        )
    }
}

fn render_argv(argv: &[String]) -> String {
    argv.iter()
        .map(|arg| {
            if arg.chars().any(char::is_whitespace) {
                format!("{arg:?}")
            } else {
                arg.clone()
            }
        })
        .collect::<Vec<_>>()
        .join(" ")

View on GitHub (pinned to a747e741ae)

Solutions

Run the same CLI command manually with the same arguments to see the tool's own stderr/stdout diagnostics.
Fix the arguments or configuration that the library passes to the CLI (they derive from the manifest and your call to `command`).
Check the CLI's required environment, permissions, and working directory.
If killed by a signal (e.g. OOM), investigate resource limits or the tool's stability.

Defensive patterns

Strategy: try-catch

Try / catch

match runner.run_external_cli(...) {
    Err(e) if e.to_string().contains("exited unsuccessfully") => {
        eprintln!("external CLI failed; rerun the command manually to see its diagnostics");
        // fall back or surface stderr to the user
        Err(e)
    }
    other => other,
}

Prevention

Run the external CLI manually with the generated arguments before automating it.
Pin and test CLI versions your manifest depends on.
Capture and log the child's stdout/stderr alongside this error.
Check the CLI's environment/working-directory requirements in CI.

When it happens

Trigger: `run_external_cli` spawns the resolved CLI via `Command`; the child process exits with a non-success status (non-zero code, or terminated by a signal), and `ensure_success` is called on the resulting `ExitStatus`.

Common situations: The external tool itself fails: bad CLI arguments built from config, the tool rejecting the working directory or environment, the tool crashing, or being killed by OOM/signals.

Related errors

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