Diagnosing and Fixing Frozen Tmux Sessions

The "Frozen" Terminal Problem

A tmux session appears frozen when you can no longer type, the screen does not update, or keybindings stop responding. This is rarely a crash of the tmux server itself; instead, it is usually a mismatch between the terminal emulator's state and the tmux server's expectations, or a local input block.

Quick Diagnostic Table

Symptom	Likely Cause	Primary Check
Complete input freeze; no echo	XOFF Flow Control	Press Ctrl+Q
Visual glitches; broken lines	TERM Variable Mismatch	echo $TERM
Session exists but won't attach	Zombied Client/Lock	tmux ls
Input lag or stuttering	SSH/Network Latency	ping [host]

Step-by-Step Recovery Process

Follow these checks in order to resolve the freeze without killing your active processes.

1. Check for Local Flow Control

Many terminal emulators support software flow control. If you accidentally press Ctrl+S, the terminal enters XOFF mode, which pauses all output to the screen. The tmux server is still running, but your view is frozen.

• Action: Press Ctrl+Q (XON).
• Verification: If the screen immediately updates with pending output, the issue was flow control.

2. Validate the TERM Environment Variable

Tmux requires a specific terminal definition to render colors and handle key sequences. If the TERM variable is set incorrectly (e.g., to xterm inside a tmux session), you may experience "ghost" characters or unresponsive shortcuts.

Run this command inside the session:

echo $TERM

Expected Result: It should return screen or tmux. If it returns xterm or vt100, the rendering will be unstable.

Fix: Exit the session and re-attach using the -u flag to force the server to use the current client's terminal settings:

# Run from the host shell
tmux attach -u

3. Clear Detached Client Hangs

Sometimes a session is "stuck" because a previous client did not detach cleanly, leaving the server in a state where it believes the window size is 0x0 or locked to a dead terminal.

1. Run tmux ls from a standard shell to confirm the session is still active.
2. If the session exists but is unresponsive, force-detach all other clients and attach fresh:

# Run from host shell with user permissions
tmux attach -d

Risk: This will forcefully disconnect any other users or scripts currently attached to that session.

4. Resolve Remote Latency (SSH)

If you are using tmux over SSH and experience "stuttering," the issue is likely the TCP connection rather than tmux. This often happens when SSH keep-alive packets are dropped by a firewall.

Diagnostic: Run ping to the host. If latency spikes correlate with the tmux freeze, modify your local ~/.ssh/config:

Host *
    ServerAliveInterval 60

When to Escalate to Server Reset

If tmux ls shows no active sessions, or if tmux attach -u results in a can't find session error despite the process existing in ps aux | grep tmux, the server process may be in a zombie state.

Final Resort: Only kill the server if you have no unsaved work in any session.

# Run from host shell
tmux kill-server

Rollback: There is no rollback for kill-server; all running processes within tmux will receive a SIGHUP and terminate.

Verification of Stability

Once recovered, verify the session is healthy by checking the window size. Run stty size inside the session and resize your terminal window. If the numbers update in real-time, the communication between the emulator and the tmux server is restored.