Troubleshooting

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

Usually caused by a corrupted or invalid configuration file. Test with a clean config first.

tmux options change between versions. Check the changelog and update deprecated options.

A running tmux server keeps the old binary's behavior after an upgrade. Detach, kill the old server, then start fresh. tmux 3.6 also changed the sixel library protocol, so a full restart is required.

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

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

Your terminal and tmux need proper italic support configured.

tmux has its own copy mode. Use tmux keybindings or configure system clipboard integration.

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

You must detach (Prefix + d) before closing terminal. Sessions persist on the tmux server.

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

Verify the prefix key and ensure your terminal isn't intercepting the key combination.

Unbind existing keys before rebinding, and ensure you're reloading the config correctly.

Enable xterm-keys and ensure proper terminal configuration.

Reduce escape time delay and optimize status bar updates.

Limit scrollback buffer and restart sessions periodically.

Ensure TPM is properly installed and initialized at the end of your config.

Verify plugins are in the correct location and reload tmux config.

tmux sessions survive SSH disconnects. SSH back in and reattach to your session.

SSH agent forwarding needs special handling in tmux. Update your environment variables.