{"record":{"id":"725e4138c9e30701","repo":"Hmbown/CodeWhale","slug":"tmux-runtime-is-unavailable-tmux-v-failed-with","errorCode":null,"errorMessage":"tmux runtime is unavailable: `tmux -V` failed with {}: {}","messagePattern":"tmux runtime is unavailable: `tmux -V` failed with (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/lane/src/runtime.rs","lineNumber":562,"sourceCode":"#[derive(Debug, Clone, Copy, PartialEq, Eq)]\nenum TmuxSessionState {\n    Present,\n    Absent,\n}\n\nfn tmux_command(socket: &Path) -> Command {\n    let mut command = Command::new(\"tmux\");\n    command.arg(\"-S\").arg(socket);\n    command\n}\n\nfn ensure_tmux_available() -> Result<()> {\n    let output = Command::new(\"tmux\")\n        .arg(\"-V\")\n        .output()\n        .context(\"tmux runtime requires the `tmux` executable\")?;\n    if !output.status.success() {\n        bail!(\n            \"tmux runtime is unavailable: `tmux -V` failed with {}: {}\",\n            output.status,\n            String::from_utf8_lossy(&output.stderr).trim()\n        );\n    }\n    Ok(())\n}\n\nfn tmux_session_state(socket: &Path, session: &str) -> Result<TmuxSessionState> {\n    let output = tmux_command(socket)\n        .args([\"has-session\", \"-t\", session])\n        .stdout(Stdio::null())\n        .stderr(Stdio::piped())\n        .output()\n        .with_context(|| format!(\"query tmux session {session}\"))?;\n    if output.status.success() {\n        return Ok(TmuxSessionState::Present);\n    }","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/lane/src/runtime.rs#L544-L580","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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.","Verify PATH for the process running the runtime: run `which tmux` from that same user/service context, not your interactive shell.","If tmux exists but fails on startup, fix or temporarily remove the user's ~/.tmux.conf and retest `tmux -V` directly.","If tmux genuinely cannot be provided, use the inline runtime instead of the tmux runtime for these lanes."],"exampleFix":"// before (CI image without tmux)\nDockerfile: FROM debian:slim  # no tmux\n\n// after\nDockerfile: FROM debian:slim\nRUN apt-get update && apt-get install -y tmux","handlingStrategy":"validation","validationCode":"fn tmux_ready() -> Result<(), String> {\n    let out = std::process::Command::new(\"tmux\").arg(\"-V\").output();\n    match out {\n        Ok(o) if o.status.success() => Ok(()),\n        Ok(o) => Err(format!(\"tmux unusable: {} ({})\", o.status, String::from_utf8_lossy(&o.stderr))),\n        Err(e) => Err(format!(\"tmux not executable: {e}\")),\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin tmux in your deployment image / dev shell (nix, Dockerfile, CI setup step).","Run `tmux -V` as a smoke test in CI before lane tests.","Assert tmux is on PATH for the service user, not just the interactive shell."],"tags":["tmux","environment","dependency"],"backgroundTag":"command-not-found","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}