tmux Troubleshooting Glossary

The Solution

tmux only sends 24-bit (True Color) to your terminal when it knows the outer terminal supports it; otherwise it maps colours to the nearest of 256. tmux 3.6+ detects this automatically when COLORTERM=truecolor is set; on older versions, or terminals that do not set it, tell tmux yourself.

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

Check what tmux detected with tmux info | grep -E "RGB|Tc" (run it inside tmux). If your terminal sets a different $TERM (for example alacritty or xterm-kitty), use that name instead of xterm*. On tmux older than 3.2 use set -as terminal-overrides ",xterm*:Tc". Use screen-256color only on old systems with no tmux-256color terminfo entry.

The Solution

This delay happens because the Escape key is the first character in many terminal "escape sequences" (like the arrow keys). Before tmux 3.5, tmux waited 500 milliseconds by default to see if another keystroke follows the Escape key; tmux 3.5 and newer wait only 10 milliseconds, so this lag usually means an older tmux or an escape-time line in your config.

Set escape-time to 10 milliseconds (check the current value with tmux show -s escape-time). Avoid 0 if you work over slow SSH links, where Escape-prefixed keys such as Alt combinations can be split:

The Solution

Every shell inside tmux keeps the $SSH_AUTH_SOCK value it started with. When you reconnect, SSH creates a new agent socket and the old path is dead. tmux's update-environment option copies the new value into the session when you attach, but only programs started after that see it; shells that were already running keep the stale path.

The robust fix is a fixed symlink that SSH refreshes on every login, plus telling tmux to always use that symlink. The second step must also remove SSH_AUTH_SOCK from update-environment, or tmux overrides the symlink on attach (we tested this on tmux 3.7c).

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.

The Solution

By default tmux starts every pane as a login shell (the default-command option is empty), so your profile files run again in each pane. On macOS, /etc/zprofile runs path_helper, which reorders $PATH and can push version-manager paths (nvm, pyenv, rbenv, Homebrew) behind the system ones, so the wrong tool, or no tool, is found.

Start panes as ordinary interactive shells instead, so they inherit the $PATH of the terminal that started tmux. Then restart the server (tmux kill-server) because existing panes keep their old environment.

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.

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.

The Solution

Undercurls use the Smulx and Setulc terminal capabilities. tmux only uses them when it knows the outer terminal supports them. On tmux 3.2+ one line enables the built-in usstyle feature; the two manual overrides below do the same on older versions.

💡 Looking for a full Neovim setup? Read our dedicated Neovim + tmux Integration Guide for seamless Ctrl-hjkl split navigation, OSC 52 clipboard sharing, and zero escape lag.

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.

Most terminals (GNOME Terminal, Konsole, Windows Terminal, Alacritty, Kitty, WezTerm, Ghostty): hold Shift while clicking and dragging.
iTerm2: hold Option. macOS Terminal.app: hold Fn.

The Solution

tmux decides whether to send UTF-8 by looking at LC_ALL, LC_CTYPE and LANG. If none says UTF-8 (common on fresh servers and in Docker), borders fall back to line-drawing codes that some terminals show as letters. The proper fix is a UTF-8 locale, for example export LANG=en_US.UTF-8 in your shell profile; tmux -u forces UTF-8 output as a quick workaround.

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

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).

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.

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 the prefix twice: Ctrl+b Ctrl+b (the default binding for send-prefix), then the key, e.g. Ctrl+b Ctrl+b c. The first stroke is swallowed by the outer session, and it passes the second stroke down the pipe to control the remote session.

The Solution

tmux draws everything itself, so your terminal's own scrollback only holds tmux's screen, not each pane's history. You must either use Copy Mode to scroll with the keyboard or enable Mouse Mode to use your wheel.

Shortcut: Prefix PgUp enters copy mode and scrolls up a page in one step. On tmux 3.6+, set -g pane-scrollbars modal shows a scrollbar while you scroll. Keep more history with set -g history-limit 50000 (default 2000 lines).