Hmbown/CodeWhale · error · anyhow::Error

tmux runtime is unavailable: `tmux -V` failed with {}: {}

Error message

tmux runtime is unavailable: `tmux -V` failed with {}: {}

What it means

ensure_tmux_available probes the runtime by running `tmux -V`; a nonzero exit produces this error including the status and trimmed stderr. It runs inside TmuxRuntime::start (unless CODEWHALE_LANE_TMUX_DRY_RUN is set) exactly so a missing or broken tmux fails closed instead of persisting a fictional Running lane — the failure is also recorded as a lane_failed log event and the lane is marked Failed.

Source

Thrown at crates/lane/src/runtime.rs:562

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TmuxSessionState {
    Present,
    Absent,
}

fn tmux_command(socket: &Path) -> Command {
    let mut command = Command::new("tmux");
    command.arg("-S").arg(socket);
    command
}

fn ensure_tmux_available() -> Result<()> {
    let output = Command::new("tmux")
        .arg("-V")
        .output()
        .context("tmux runtime requires the `tmux` executable")?;
    if !output.status.success() {
        bail!(
            "tmux runtime is unavailable: `tmux -V` failed with {}: {}",
            output.status,
            String::from_utf8_lossy(&output.stderr).trim()
        );
    }
    Ok(())
}

fn tmux_session_state(socket: &Path, session: &str) -> Result<TmuxSessionState> {
    let output = tmux_command(socket)
        .args(["has-session", "-t", session])
        .stdout(Stdio::null())
        .stderr(Stdio::piped())
        .output()
        .with_context(|| format!("query tmux session {session}"))?;
    if output.status.success() {
        return Ok(TmuxSessionState::Present);
    }

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Run `tmux -V` in the same shell/environment to see the exact failure
2. Install or repair tmux (package manager) and confirm it is the real binary (which tmux)
3. Use the inline runtime instead when no terminal multiplexer is available
4. For tests that must not spawn processes, set CODEWHALE_LANE_TMUX_DRY_RUN — but never in production paths

Example fix

# before
# container image without tmux; lane start with backend "tmux"

# after (Dockerfile)
RUN apt-get update && apt-get install -y tmux && rm -rf /var/lib/apt/lists/*
# verify: tmux -V

fn tmux_available() -> bool {
    std::process::Command::new("tmux")
        .arg("-V")
        .output()
        .map(|o| o.status.success())
        .unwrap_or(false)
}

let backend = if tmux_available() { "tmux" } else { "inline" };

When it happens

Trigger: TmuxRuntime::start with a tmux binary on PATH that exits nonzero for -V: broken installation, wrapper script erroring, incompatible tmux build, or library loader failures. (A missing executable yields the 'requires the tmux executable' context error instead.)

Common situations: Minimal containers/CI images without tmux; an alias or shim named tmux shadowing the real binary; tmux installed but failing to run due to missing libc/terminfo; local bins earlier in PATH containing a broken script.

Related errors

• unknown runtime backend `{other}` (use tmux|inline|vm|ci)
• tmux has-session for {session} failed with {}: {}
• tmux session {session} remains active after kill-session ({s
• tmux runtime requires a non-empty command
• lane `{}` was stopped before tmux dry-run start completed

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/725e4138c9e30701. Report an issue: GitHub.