Troubleshooting Guide

Updated for tmux 3.4

Common tmux problems and their solutions. Find quick fixes for installation errors, display issues, key binding problems, and more.

Last updated: January 23, 2025

Quick Navigation

Jump to your problem category

🔧Installation & Setup Issues 🎨Display & Color Issues 📋Copy/Paste Problems 🔌Session & Connection Issues ⌨️Key Binding & Control Issues ⚡Performance Issues

🔧Installation & Setup Issues

❌Command not found: tmux

Symptoms:

•Terminal shows 'tmux: command not found'
•bash: tmux: command not found
•zsh: command not found: tmux

✅Solution:

tmux is not installed or not in your PATH. Install it using your package manager, then restart your terminal.

bash

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt update && sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

# Arch Linux
sudo pacman -S tmux

# Verify installation
tmux -V

💡Prevention:

Always verify installation with 'tmux -V' after installing.

❌tmux won't start or crashes immediately

Symptoms:

•tmux starts then immediately exits
•Error: 'lost server' or 'no server running'
•tmux window closes instantly

✅Solution:

Usually caused by a corrupted configuration file. Check ~/.tmux.conf for syntax errors.

bash

# Temporarily bypass config to test
tmux -f /dev/null

# Check config for errors
tmux -f ~/.tmux.conf source-file ~/.tmux.conf

# Rename config to disable it
mv ~/.tmux.conf ~/.tmux.conf.backup

# Start fresh tmux
tmux

💡Prevention:

Always test configuration changes with 'tmux source-file ~/.tmux.conf' before restarting.

🎨Display & Color Issues

❌Colors look wrong or washed out

Symptoms:

•Terminal colors don't match outside tmux
•Vim/Neovim colors incorrect
•256 colors not working
•True color (24-bit) not working

✅Solution:

Configure tmux to use proper terminal type and enable true color support.

bash

# Add to ~/.tmux.conf

# For 256 color support
set -g default-terminal "screen-256color"
# OR for better compatibility
set -g default-terminal "tmux-256color"

# For true color (24-bit) support
set -as terminal-features ",xterm-256color:RGB"
# OR older tmux versions
set -ga terminal-overrides ",xterm-256color:Tc"

# Reload config
# Press Ctrl+b : then type:
source-file ~/.tmux.conf

💡Prevention:

Set default-terminal in ~/.tmux.conf before customizing colors. Test with 'echo $TERM' inside tmux (should show 'tmux-256color' or 'screen-256color').

❌Status bar not showing or looks broken

Symptoms:

•Missing status bar at bottom
•Status bar characters garbled
•Icons showing as boxes or question marks

✅Solution:

Enable status bar and ensure your terminal font supports Unicode/Powerline symbols.

bash

# Add to ~/.tmux.conf

# Enable status bar
set -g status on

# Set status bar position (top or bottom)
set -g status-position bottom

# Simple status bar (no special characters)
set -g status-left '[#S] '
set -g status-right '%H:%M %d-%b-%y'

# Refresh status every second
set -g status-interval 1

💡Prevention:

Use simple ASCII characters in status bar or install a Powerline-compatible font (Nerd Fonts recommended).

📋Copy/Paste Problems

❌Can't copy or paste text

Symptoms:

•Selected text doesn't copy
•Ctrl+C/Ctrl+V don't work
•Copy works but paste doesn't

✅Solution:

tmux has its own copy mode. Use tmux keybindings or enable mouse mode for system clipboard integration.

bash

# Native tmux copy/paste
Ctrl+b [          # Enter copy mode
Space             # Start selection
Enter             # Copy selection
Ctrl+b ]          # Paste

# Enable mouse mode in ~/.tmux.conf
set -g mouse on

# Install xclip (Linux) for system clipboard
sudo apt install xclip

# macOS clipboard integration (add to ~/.tmux.conf)
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
bind-key -T copy-mode-vi MouseDragEnd1Pane send-keys -X copy-pipe-and-cancel "pbcopy"

# Linux clipboard integration
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"

💡Prevention:

Enable mouse mode and install clipboard tools (xclip/pbcopy). Consider using tmux-yank plugin for better clipboard integration.

❌Can't scroll up to see previous output

Symptoms:

•Mouse wheel doesn't scroll
•Can't see command history
•Terminal output disappears

✅Solution:

Enter copy mode to scroll, or enable mouse mode for mouse wheel scrolling.

bash

# Manual scrolling (without mouse)
Ctrl+b [          # Enter copy mode
Page Up/Down      # Scroll pages
Arrow keys        # Scroll lines
q or Esc          # Exit copy mode

# Enable mouse scrolling in ~/.tmux.conf
set -g mouse on

# Increase scrollback buffer
set -g history-limit 10000

# Vi-style navigation in copy mode
setw -g mode-keys vi

💡Prevention:

Enable mouse mode and increase history-limit to 10000+ lines.

🔌Session & Connection Issues

❌Session lost when terminal closes

Symptoms:

•tmux session disappears when closing terminal
•Can't reattach to session
•All work lost after disconnect

✅Solution:

You must detach (Ctrl+b d) before closing terminal. Sessions are preserved on the server.

bash

# Always detach before closing terminal
Ctrl+b d

# List existing sessions
tmux ls

# Reattach to most recent session
tmux attach

# Reattach to specific session
tmux attach -t session-name

# Kill a hung session
tmux kill-session -t session-name

💡Prevention:

Always use Ctrl+b d to detach. For persistent sessions across reboots, use tmux-resurrect plugin.

❌Can't attach: 'sessions should be nested with care'

Symptoms:

•Warning when running tmux inside tmux
•Nested tmux sessions causing confusion

✅Solution:

You're trying to run tmux inside an existing tmux session. This is rarely needed.

bash

# Check if already in tmux
echo $TMUX

# Exit current tmux session first
Ctrl+b d

# Or bypass the check (not recommended)
TMUX= tmux

# List all sessions from outside tmux
tmux ls

# Attach to existing session instead
tmux attach -t session-name

💡Prevention:

Always check 'echo $TMUX' before starting tmux. Use sessions/windows instead of nesting.

❌SSH connection drops and loses tmux session

Symptoms:

•Session lost after network interruption
•Can't reconnect after SSH timeout

✅Solution:

tmux sessions survive SSH disconnects. Just SSH back in and reattach.

bash

# After SSH reconnects
tmux ls              # List sessions
tmux attach          # Reattach to last session
tmux attach -t name  # Reattach to specific session

# For automatic reattachment, add to ~/.bashrc or ~/.zshrc
if command -v tmux &> /dev/null && [ -z "$TMUX" ]; then
  tmux attach -t default || tmux new -s default
fi

💡Prevention:

Use 'mosh' (mobile shell) instead of SSH for better connection resilience. Consider tmux-continuum for automatic session saving.

⌨️Key Binding & Control Issues

❌Key bindings not working

Symptoms:

•Ctrl+b doesn't do anything
•Custom keybindings don't work
•Commands work but shortcuts don't

✅Solution:

Verify you're pressing the correct prefix key and reload configuration after changes.

bash

# Test default prefix (Ctrl+b)
Ctrl+b ?        # Show all key bindings

# Check current prefix
tmux show-options -g | grep prefix

# Reload config after changes
Ctrl+b : source-file ~/.tmux.conf

# Or bind reload to a key (add to ~/.tmux.conf)
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# Reset to default config
tmux -f /dev/null

💡Prevention:

Always reload config with 'Ctrl+b : source-file ~/.tmux.conf' after editing ~/.tmux.conf. Add a reload keybinding.

❌Can't use Ctrl+arrow keys or other key combinations

Symptoms:

•Ctrl+Left/Right doesn't work
•Special key combinations ignored

✅Solution:

Your terminal emulator may not send the right key codes. Enable xterm-keys.

bash

# Add to ~/.tmux.conf
setw -g xterm-keys on

# Alternative: bind keys explicitly
bind -n C-Left previous-window
bind -n C-Right next-window

💡Prevention:

Use a modern terminal emulator (iTerm2, Alacritty, Kitty, etc.).

⚡Performance Issues

❌tmux feels slow or laggy

Symptoms:

•Typing has noticeable delay
•Screen updates slowly
•High CPU usage

✅Solution:

Reduce escape time delay and optimize status bar refresh rate.

bash

# Add to ~/.tmux.conf

# Reduce escape time (fixes Vim delay)
set -sg escape-time 0

# Reduce status bar refresh rate
set -g status-interval 5

# Disable activity monitoring if not needed
setw -g monitor-activity off

# Use aggressive resize
setw -g aggressive-resize on

💡Prevention:

Don't run CPU-intensive commands in status bar. Keep status-interval at 5+ seconds.

❌Memory usage increasing over time

Symptoms:

•tmux process using lots of RAM
•System slowdown with long-running sessions

✅Solution:

Reduce scrollback buffer size or restart sessions periodically.

bash

# Add to ~/.tmux.conf
set -g history-limit 5000

# Clear scrollback manually
Ctrl+b : clear-history

# Kill and restart session
tmux kill-session -t session-name
tmux new -s session-name

💡Prevention:

Set history-limit to reasonable value (2000-10000). Don't use unlimited scrollback.

🐛General Debugging Tips

When nothing else works, try these

Check tmux version:

tmux -V

Many issues are fixed in newer versions. Update if you're running an old version.

Test with clean config:

tmux -f /dev/null

Starts tmux without loading ~/.tmux.conf to test if config is the issue.

View current settings:

tmux show-options -g

Shows all global options. Add -s for server options, -w for window options.

Kill all tmux processes:

tmux kill-server

Nuclear option: kills all sessions and server. Use when tmux is completely broken.

Still Need Help?

Can't find the solution you need? Here are more resources:

📚 FAQ Page

Check our comprehensive FAQ for more common questions

Browse FAQ →

💬 Community Help

Ask the tmux community

GitHub Discussions →

📖 Man Page

Official tmux manual for detailed reference

man tmux

🐛 Report Bug

Found a bug? Report it to the maintainers

GitHub Issues →