Troubleshooting Guide

Updated for tmux 3.6

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

Verified Dec 2025 for tmux 3.6

8 min read

intermediate

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 →

Troubleshooting Guide

Quick Navigation

🔧Installation & Setup Issues

❌Command not found: tmux

Symptoms:

✅Solution:

💡Prevention:

❌tmux won't start or crashes immediately

Symptoms:

✅Solution:

💡Prevention:

🎨Display & Color Issues

❌Colors look wrong or washed out

Symptoms:

✅Solution:

💡Prevention:

❌Status bar not showing or looks broken

Symptoms:

✅Solution:

💡Prevention:

📋Copy/Paste Problems

❌Can't copy or paste text

Symptoms:

✅Solution:

💡Prevention:

❌Can't scroll up to see previous output

Symptoms:

✅Solution:

💡Prevention:

🔌Session & Connection Issues

❌Session lost when terminal closes

Symptoms:

✅Solution:

💡Prevention:

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

Symptoms:

✅Solution:

💡Prevention:

❌SSH connection drops and loses tmux session

Symptoms:

✅Solution:

💡Prevention:

⌨️Key Binding & Control Issues

❌Key bindings not working

Symptoms:

✅Solution:

💡Prevention:

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

Symptoms:

✅Solution:

💡Prevention:

⚡Performance Issues

❌tmux feels slow or laggy

Symptoms:

✅Solution:

💡Prevention:

❌Memory usage increasing over time

Symptoms:

✅Solution:

💡Prevention:

🐛General Debugging Tips

Check tmux version:

Test with clean config:

View current settings:

Kill all tmux processes:

Still Need Help?

📚 FAQ Page

💬 Community Help

📖 Man Page

🐛 Report Bug

Related Topics

Installation Guide

Configuration

FAQ

Getting Started