Hmbown/CodeWhale · error

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

Error message

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

What it means

This error is thrown by the lane runtime's `ensure_tmux_available` preflight check before any tmux session is created. The library shells out to `tmux -V` to verify the tmux executable exists and is functional; if the command exits nonzero, the runtime refuses to start a lane, because a lane recorded as Running without a working tmux binary would be fictional state. The message includes the exit status and trimmed stderr so the developer can see exactly why tmux rejected the probe.

Solutions

1. Install tmux (`apt-get install tmux`, `brew install tmux`, or the equivalent for your platform) and confirm `tmux -V` succeeds in the same environment the lane runtime runs in.
2. Verify PATH for the process running the runtime: run `which tmux` from that same user/service context, not your interactive shell.
3. If tmux exists but fails on startup, fix or temporarily remove the user's ~/.tmux.conf and retest `tmux -V` directly.
4. If tmux genuinely cannot be provided, use the inline runtime instead of the tmux runtime for these lanes.

Example fix

// before (CI image without tmux)
Dockerfile: FROM debian:slim  # no tmux

// after
Dockerfile: FROM debian:slim
RUN apt-get update && apt-get install -y tmux

fn tmux_ready() -> Result<(), String> {
    let out = std::process::Command::new("tmux").arg("-V").output();
    match out {
        Ok(o) if o.status.success() => Ok(()),
        Ok(o) => Err(format!("tmux unusable: {} ({})", o.status, String::from_utf8_lossy(&o.stderr))),
        Err(e) => Err(format!("tmux not executable: {e}")),
    }
}

When it happens

Trigger: Calling `LaneRuntime::start` (via `start`) when the `tmux` binary is missing from PATH, is a broken shim, is a version too old to support `-V` semantics, or when the environment (e.g. a restricted container or stripped-down CI image) cannot execute it. Also triggered when `tmux` exists but its own startup fails (corrupt config, no /dev/ptys).

Common situations: Deploying to a minimal Docker image or Nix environment without tmux installed; running the lane runtime inside a Windows/subsystem where tmux is unavailable; a PATH mismatch where the tmux binary is only available in an interactive shell; a broken tmux.conf that makes `tmux -V` abort with an error before printing the version.

Related errors

• tmux attach unavailable
• active plugin registry is missing its pre-dotenv…
• AT-SPI walk failed — is python3-pyatspi installed and the…
• braille-mark.py requires pillow (`pip install pillow`)
• building bundle fetch client failed

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/725e4138c9e30701. Report an issue: GitHub.

Appendix: 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 73e0f67d83)