Troubleshooting Guide

Fresh

Solutions for common tmux problems.

Installation Issues

"libevent not found" during build

Cause: Missing libevent development library.

Solution:

Debian/Ubuntu

sudo apt-get install libevent-dev

RHEL/CentOS

sudo yum install libevent-devel

macOS

brew install libevent

"ncurses not found" during build

Cause: Missing ncurses development library.

Solution:

Debian/Ubuntu

sudo apt-get install ncurses-dev

RHEL/CentOS

sudo yum install ncurses-devel

"C compiler cannot create executables"

Cause: No C compiler installed or broken configuration.

Solution:

# Debian/Ubuntu
sudo apt-get install build-essential

# RHEL/CentOS
sudo yum groupinstall "Development Tools"

# Check CFLAGS isn't broken
echo $CFLAGS
unset CFLAGS  # If it has strange values

tmux won't start after local install

Cause: Library path not set.

Solution:

# Set library path
export LD_LIBRARY_PATH=$HOME/local/lib:$LD_LIBRARY_PATH

# Add to ~/.bashrc for persistence
echo 'export LD_LIBRARY_PATH=$HOME/local/lib:$LD_LIBRARY_PATH' >> ~/.bashrc

Session Issues

"no sessions" when trying to attach

Cause: No tmux sessions exist.

Solution:

# Create a new session
tmux new -s mysession

# Or use attach-or-create
tmux new-session -A -s mysession

"sessions should be nested with care"

Cause: Trying to start tmux inside tmux.

Solution:

# Option 1: Create new window instead
Ctrl+b c

# Option 2: Detach first
Ctrl+b d
tmux new -s another

# Option 3: Force (not recommended)
TMUX= tmux new

Session lost after SSH disconnect

Cause: This is actually normal! Session persists.

Solution:

# Reconnect via SSH
ssh user@server

# Reattach to session
tmux attach
# or
tmux attach -t sessionname

Can't attach - "already attached"

Cause: Session is attached elsewhere.

Solution:

# Force attach (detaches other clients)
tmux attach -dt sessionname

Window/Pane Issues

Pane too small to split

Cause: Current pane dimensions below minimum.

Solution:

• Make terminal window larger
• Close other panes
• Or resize existing panes first:

  Ctrl+b :resize-pane -R 20

Window numbers have gaps (0, 2, 5)

Cause: Windows were closed without renumbering.

Solution:

# Renumber windows
Ctrl+b :move-window -r

# Enable automatic renumbering
# Add to ~/.tmux.conf:
set -g renumber-windows on

Lost track of panes

Solution:

# Show pane numbers
Ctrl+b q

# Show pane info
Ctrl+b :display-panes

Zoom not working

Cause: Already zoomed or single pane.

Solution:

# Check if zoomed (status shows [Z])
# Toggle zoom off then on
Ctrl+b z
Ctrl+b z

Copy/Paste Issues

Can't enter copy mode

Solution:

# Make sure prefix works first
Ctrl+b ?  # Should show help

# Then try
Ctrl+b [

Vi keys not working in copy mode

Cause: Vi mode not enabled.

Solution:

# Enable temporarily
Ctrl+b :setw mode-keys vi

# Enable permanently in ~/.tmux.conf
setw -g mode-keys vi

Paste not working

Cause: Nothing in buffer.

Solution:

# Check buffers
Ctrl+b :list-buffers

# If empty, copy something first:
# 1. Ctrl+b [
# 2. Navigate to text
# 3. Space to start selection
# 4. Move to end
# 5. Enter to copy
# 6. Ctrl+b ] to paste

Need to copy to system clipboard

Solution for macOS:

# Add to ~/.tmux.conf
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

Solution for Linux (with xclip):

# Install xclip
sudo apt install xclip

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

Configuration Issues

Config not loading

Cause: File not found or syntax error.

Solution:

# Check file exists
ls -la ~/.tmux.conf

# Try loading manually (shows errors)
tmux source-file ~/.tmux.conf

# Check for typos in config

Keybinding not working

Solution:

# Check current bindings
Ctrl+b ?

# Or search for specific key
tmux list-keys | grep <key>

# May need to unbind first
unbind <key>
bind <key> <command>

Colors look wrong

Cause: Terminal type mismatch.

Solution:

# Add to ~/.tmux.conf
set -g default-terminal "screen-256color"
# or
set -g default-terminal "tmux-256color"

# Verify terminal supports colors
echo $TERM
tput colors  # Should show 256

Status bar not updating

Solution:

# Set update interval
set -g status-interval 5

# Force refresh
Ctrl+b :refresh-client

Performance Issues

Slow/laggy response

Solutions:

# Reduce escape time (helps with vim)
set -sg escape-time 0

# Reduce history limit
set -g history-limit 5000

# Simplify status bar
set -g status-right ""

High memory usage

Cause: Large scroll buffers.

Solution:

# Reduce history
set -g history-limit 2000

# Clear history manually
Ctrl+b :clear-history

Display Issues

Screen garbled/corrupted

Solution:

# Redraw screen
Ctrl+b r  # If you have reload bound

# Or force redraw
Ctrl+b :refresh-client

# From outside tmux
tmux refresh-client -t sessionname

Wrong terminal size

Cause: Smaller client attached.

Solution:

# Detach smaller client
tmux attach -d

# Or set aggressive resize
# In ~/.tmux.conf:
setw -g aggressive-resize on

Quick Diagnostic Commands

# tmux version
tmux -V

# List sessions
tmux ls

# List windows
tmux list-windows

# List panes
tmux list-panes

# List key bindings
tmux list-keys

# Show options
tmux show-options -g

# Show window options
tmux show-options -w

# Server info
tmux info

Getting Help

# Built-in help
Ctrl+b ?

# Man page
man tmux

# Online resources
# - https://github.com/tmux/tmux/wiki
# - https://tmuxcheatsheet.com

See Also

• SOP: Installation
• SOP: Configuration
• Commands Reference