Fix Your Terminal

tmux Troubleshooting Glossary

Direct, copy-able fixes for the 13 most common bugs: scrolling history, broken SSH agents, True Color rendering, and more.

1. Fix "Washed Out" Colors (True Color Support)

You spend hours configuring a beautiful Neovim theme, but when you launch it inside tmux, the background looks grayed out and the syntax highlighting is wrong.

The Solution

By default, tmux strips out 24-bit color (True Color) metadata unless you explicitly tell it that your outer terminal emulator (like iTerm2, Alacritty, or Windows Terminal) supports it.

Ensure these two lines exist in your ~/.tmux.conf:

~/.tmux.conf

# Enable RGB colour if running in xterm(1)

set-option -sa terminal-overrides ",xterm*:Tc"


# Default terminal is 256 colors

set -g default-terminal "screen-256color"

Note: If you are using a modern terminal that advertises itself as alacritty or kitty, replace xterm* with alacritty or * to match its TERM string. For example: set-option -sa terminal-overrides ",*:Tc"

2. Fix Vim / Neovim `Escape` Key Delay

When you press Escape to leave Insert mode in Vim, there is a frustrating half-second pause before the cursor responds.

The Solution

This delay happens because the Escape key is the first character in many terminal "escape sequences" (like the arrow keys). tmux waits for 500 milliseconds by default to see if another keystroke follows the Escape key.

You can eliminate this wait entirely by reducing the escape-time variable to 10 milliseconds or 0 in your config:

~/.tmux.conf

# Remove delay for exiting insert mode with ESC in Neovim

set -sg escape-time 10

3. SSH Agent Broken Upon Reconnecting

You detach from your tmux session, go home, and SSH back in. When you reattach, Git pushes and remote SSH commands fail maliciously with Permission denied (publickey).

The Solution

When tmux starts, it caches your original $SSH_AUTH_SOCK environment variable. When you reconnect later, the original socket file is dead, but tmux hasn't updated the variable for the running session.

The most robust fix is to create a static symlink for your SSH socket in ~/.ssh/rc, and tell tmux to point directly to that symlink rather than relying on dynamic updates.

1. Create ~/.ssh/rc (on server)

# Every time you SSH in, symlink the active socket to a fixed path

if test "$SSH_AUTH_SOCK" ; then

  ln -sf $SSH_AUTH_SOCK ~/.ssh/ssh_auth_sock

fi

2. Add to ~/.tmux.conf

# Force tmux to always point to the static symlink

setenv -g SSH_AUTH_SOCK $HOME/.ssh/ssh_auth_sock

4. Terminal "Frozen" (No Keyboard Input)

You are typing quickly, and suddenly the terminal stops responding. You can't type anything, and the screen is completely frozen, leading you to believe that the tmux server has crashed.

The Solution

You accidentally pressed Ctrl+s, which is the legacy terminal command for XOFF (Flow Control), instructing the terminal to stop processing output.

Press Ctrl+q (XON) immediately to unfreeze the terminal. To prevent this entirely in the future, disable flow control in your shell configuration profile.

~/.bashrc OR ~/.zshrc

# Disable terminal flow control (Ctrl+s hang)

stty -ixon

5. Commands Not Found ($PATH Issues)

You run a command like npm or rvm in your normal terminal perfectly. But when you create a tmux window, bash responds with command not found.

The Solution

By default, tmux starts a "login shell". However, on some systems (like macOS), it behaves as an interactive non-login shell, meaning it does not automatically re-source your ~/.bash_profile or ~/.zprofile where your $PATH variables are declared.

You can instruct tmux to explicitly launch your default shell as a login shell every time, guaranteeing identical environments.

~/.tmux.conf

# Force tmux to always spawn login shells

set -g default-command "${SHELL}"

6. Fix macOS Clipboard (pbcopy / pbpaste)

You highlight text in tmux copy-mode, press y to yank it, but when you go to paste it into a web browser, your system clipboard is empty.

The Solution

Modern tmux handles this via the copy-pipe command. You must explicitly tell tmux to pipe the copied text output into the native macOS clipboard daemon, pbcopy.

~/.tmux.conf

# Use vi keys in copy mode

setw -g mode-keys vi


# Bind 'y' to pipe selection to macOS clipboard

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 Users: Replace pbcopy with xclip -in -selection clipboard or wl-copy (for Wayland). Alternately, use the tmux-yank plugin, which handles OS detection automatically.

7. Missing Undercurls / Squiggly Lines (Neovim)

LSP diagnostics and spellcheck in modern Neovim rely on colored undercurls (squiggly underlines) to denote errors. In tmux, these degrade to standard white underlines or disappear completely.

The Solution

Terminal emulators define an escape sequence capability (`Smulx`) to trigger undercurls. By default, tmux's internal terminfo database doesn't pass this downstream. You must explicitly tell tmux how to pipe these sequences.

~/.tmux.conf

# Undercurl support

set -as terminal-overrides ',*:Smulx=\E[4::%p1%dm'


# Support for colored underlines

set -as terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m'

8. Cannot Copy Text Normally in Mouse Mode

You enabled set -g mouse on to scroll smoothly, but now when you click and drag over text you want to quickly copy from a pane, it selects entire rows across splits instead of just the text you want.

The Solution

When mouse mode is enabled, tmux intercepts all mouse events. To bypass tmux temporarily and use your outer terminal emulator's native text selection tooling, you must hold down a modifier key.

Windows / Linux Terminals: Hold down the Shift key while clicking and dragging.
macOS Terminals (iTerm2 / Alacritty): Hold down the Fn or Option (Alt) key while clicking and dragging.

9. Strange Characters & Rendering Issues

Pane borders look like rows of "q", "x", and "j" characters, or emojis / powerline font icons are failing to render properly.

The Solution

If tmux doesn't detect a UTF-8 environment, it falls back to basic ASCII line-drawing, which incorrectly translates modern box-drawing characters. You can force UTF-8 initialization.

Launch tmux explicitly with the -u flag from your shell, or alias it in your ~/.bashrc or ~/.zshrc:

~/.zshrc OR ~/.bashrc

# Force tmux to assume the terminal supports UTF-8

alias tmux="tmux -u"

10. Rebinding Default Prefix Issues

You tried to change the default Ctrl+b prefix to Ctrl+a, but now neither of them work correctly, or the new prefix isn't passing through to embedded applications.

The Solution

When changing the prefix in tmux, you must explicitly clear (unbind) the old prefix to prevent collisions, set the new prefix, and rebind the send-prefix command so you can pass the key combination to other terminal apps (like Vim or nested shell jobs).

~/.tmux.conf

# Unbind default prefix

unbind C-b


# Set new prefix to Ctrl+a

set -g prefix C-a


# Ensure that we can send Ctrl+a to other apps (pressing it twice)

bind C-a send-prefix

11. Configuration File Changes Not Applying

You copy-pasted a snippet into ~/.tmux.conf, saved the file, and closed your terminal. You open a new terminal window, but the changes aren't there.

The Solution

Tmux is a client-server architecture. Closing a terminal merely detaches the client; the underlying server never restarted, and therefore it never re-read the configuration file.

You can force the live server to re-evaluate the config file without killing it by using the source-file command.

Inside a running tmux session

# Press Prefix (Ctrl+b), then type colon ":" to enter the command prompt

:source-file ~/.tmux.conf

Better Fix: Add a hotkey to ~/.tmux.conf

# Press Prefix + r to quickly reload the config file

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

12. Controlling Nested tmux Sessions

You have a tmux session open on your laptop. Inside a pane, you SSH into a remote server, and open tmux there. Now you have "tmuxception". When you press your prefix to create a pane, it splits your outer laptop session, not the internal server session.

The Solution

The outermost tmux server always intercepts the prefix key first. To send the prefix command to the "nested" inner session, you must press the configured send-prefix sequence.

If your outer session uses the default Ctrl+b prefix, press Ctrl+b followed directly by another b (or hit the prefix twice, depending on your config). The first stroke is swallowed by the outer session, and it passes the second stroke down the pipe to control the remote session.

~/.tmux.conf

# If your prefix is Ctrl+a, bind Ctrl+a to send the prefix key inward

bind C-a send-prefix

13. How to Scroll Up (History & Mouse)

You try to use your terminal's scroll bar or mouse wheel to see previous output, but it either does nothing or scrolls your command history instead of the terminal buffer.

The Solution

By default, tmux captures the terminal's alternate screen, which disables the standard terminal scroll bar. You must either use Copy Mode to scroll with the keyboard or enable Mouse Mode to use your wheel.

Option A: Enable Mouse Scrolling (Recommended)

# Add this to ~/.tmux.conf to enable mouse wheel scrolling

set -g mouse on

Option B: The Keyboard Method (Native)

# 1. Enter "Scroll Mode" (Copy Mode)

Press Prefix then [


# 2. Navigate history using keys

Use ↑ ↓ or Page Up Page Down


# 3. Exit back to prompt

Press q