Skip to main content

Common Errors and Fixes

Most tmux problems fall into a small number of root causes. This lesson covers each category with symptoms, root cause, and the fix.

Learning Focus

For each error, the goal is to understand the root cause — not just copy the fix — so you can solve variations on your own.

Error: "no server running"​

Symptom:

error connecting to /tmp/tmux-1000/default (No such file or directory)

Root cause: The tmux server is not running. The socket file does not exist.

Fix:

# There is nothing to attach to — start a new session
tmux new -s work

Error: "session not found"​

Symptom:

can't find session: mywork

Root cause: The session name does not match any running sessions.

Fix:

# List what actually exists
tmux ls

# Attach to the correct name
tmux attach -t actual-session-name

Issue: Config Changes Not Applied​

Symptom: Changes to ~/.tmux.conf don't seem to work.

Root cause: Tmux reads the config on startup only. Running sessions are unaffected until you reload.

Fix:

# Reload without restarting
tmux source-file ~/.tmux.conf

# Or from inside tmux
Ctrl+b :
:source-file ~/.tmux.conf
tip

Bind a reload key so you never forget:

bind r source-file ~/.tmux.conf \; display "Reloaded!"

Issue: Colors Look Wrong​

Symptom: Status bar looks plain, no 256 colors, or color is broken.

Root cause: Terminal type mismatch.

Fix:

~/.tmux.conf
set -g default-terminal "screen-256color"
# or for true color:
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"

Check your terminal's reported colors:

echo $TERM
tput colors

Issue: Prefix Key Doesn't Work​

Symptom: Ctrl+b does nothing, or sends control codes to the shell.

Root causes:

  • You changed the prefix in config but the old tmux session loaded the old config
  • Another application (like vim) is capturing the key

Fix:

# Verify the current prefix
tmux show-option -g prefix

# Reload config
tmux source-file ~/.tmux.conf

# Test with a fresh session
tmux new -s test

If vim or another tool captures Ctrl+b, consider changing the prefix to Ctrl+a in your config.

Issue: Pane Zoom Stuck​

Symptom: Pane is zoomed (full screen) and Ctrl+b z doesn't unzoom.

Root cause: Usually nothing — just press Ctrl+b z again.

Fix:

Ctrl+b z        # toggle zoom

If unresponsive:

:resize-pane -Z   # via command prompt

Issue: Copy Mode Doesn't Copy to Clipboard​

Symptom: y in copy mode doesn't put text in the system clipboard.

Root causes:

  • No clipboard utility installed (xclip or xsel on Linux)
  • Running on a headless server without a display
  • Config binding not applied

Fix:

# Install xclip
sudo apt install -y xclip

# Add to ~/.tmux.conf:
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -i -sel clipboard"

On headless servers: use Ctrl+b ] (tmux internal paste) instead of system clipboard.

Issue: Nested Tmux Prefix Confusion​

Symptom: Commands go to the outer tmux session instead of the inner one.

Root cause: You have tmux inside tmux. Both respond to the same prefix.

Fix:

  • Press the prefix twice to send it to the inner session: Ctrl+b Ctrl+b d (detaches inner)
  • Or use a different prefix for the inner session

Issue: Sessions Killed After Logout​

Symptom: All sessions are lost when you log out.

Root cause: User lingering is not enabled; systemd stops user processes on logout.

Fix:

sudo loginctl enable-linger $USER

This keeps your user processes (including tmux server) running after logout.

Issue: tmux -V Shows Old Version​

Symptom: You installed tmux but get an old version, or new features don't work.

Fix:

which tmux
tmux -V
# If from package manager:
sudo apt update && sudo apt install -y tmux

For the latest version, build from source or use a PPA/backport.

Diagnostic Commands Summary​

# Version
tmux -V

# List all running sessions
tmux ls

# Show current global options
tmux show-options -g

# Show key bindings
tmux list-keys

# Show environment in tmux
tmux show-environment

# Check server process
pgrep -la tmux

What's Next​