Hmbown/CodeWhale · error

tmux new-session failed with

Error message

tmux new-session failed with {status}

What it means

When the tmux runtime actually spawns the session, it runs the prepared `tmux new-session ...` command and checks the exit status; a nonzero status means tmux refused to create the session, so `start` fails. The spawn runs under a rollback guard that stops a half-created session, so this error surfaces only when tmux itself rejected the new-session invocation.

Solutions

1. Re-run the exact `tmux -S <socket> new-session ...` command by hand to see tmux's stderr.
2. Check whether a session with the same name already exists on the socket (`tmux -S <socket> has-session -t <name>`) and stop/rename it.
3. Verify the pinned socket directory exists and is writable by the runtime user.
4. Simplify the command/flags until tmux accepts them, then re-add pieces to isolate the offending flag or quoting.

Example fix

// before (duplicate session name)
tmux -S /tmp/lane.sock new-session -d -s lane-42 'bash'
# duplicate session: lane-42

// after: use a unique session name or kill the old one
tmux -S /tmp/lane.sock kill-session -t lane-42 && tmux -S /tmp/lane.sock new-session -d -s lane-42 'bash'

// pre-check: socket dir writable and session name free
assert_socket_dir_writable(socket)?;
if tmux_session_state(socket, session)? == TmuxSessionState::Present {
    return Err(format!("session {session} already exists on {socket}"));
}

When it happens

Trigger: Calling `start` (non-dry-run) where the `tmux new-session` invocation exits nonzero — invalid tmux flags, an unresolvable socket path, session name conflicts, a command that tmux's parser rejects, or the tmux server failing to start on the pinned socket.

Common situations: Stale or unwritable socket path in the tmux_socket pin; a session with the same name already existing on that socket; tmux flag incompatibilities with an older/newer tmux version; a shell command string with quoting issues that tmux misparses.

Related errors

• Failed to run command
• tmux has-session for
• tmux session remains active after kill-session ( )
• Cannot resolve current binary path
• Cloud agent harness exited with code

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

Appendix: source

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

        );

        let mut cmd = tmux_command(&socket);
        cmd.args(["new-session", "-d", "-s", &session]);
        if let Some(cwd) = cwd.as_ref() {
            cmd.arg("-c").arg(cwd);
        }
        cmd.arg(shell_cmd);
        let proposed_record = record.clone();
        let spawned = std::cell::Cell::new(false);
        let rolled_back = std::cell::Cell::new(false);
        match registry.mark_running_if_pending_with(
            record,
            || {
                let status = cmd
                    .status()
                    .with_context(|| format!("spawn tmux session {session}"))?;
                if !status.success() {
                    bail!("tmux new-session failed with {status}");
                }
                spawned.set(true);
                Ok(())
            },
            || {
                stop_tmux_session(&socket, &session)?;
                rolled_back.set(true);
                Ok(())
            },
        ) {
            Ok(true) => {}
            Ok(false) => {
                if let Some(path) = environment_path.as_deref() {
                    remove_file_if_present(path)?;
                }
                let mut stopped_record = proposed_record;
                stopped_record.stopped_at = record.stopped_at.clone();
                self.cleanup_worktree(&stopped_record)?;

View on GitHub (pinned to 73e0f67d83)