tmux Troubleshooting

tmux Troubleshooting

Symptom → cause → fix. The page to skim when something feels off.

---

❌ -bash: set: -g: invalid option

Symptom. You paste lines from ~/.tmux.conf (e.g. set -g mouse on) into a bash shell and get:

-bash: set: -g: invalid option

…or similar errors about bind, setw, unbind.

Cause. Those lines are tmux commands, not bash commands. The bash set builtin is a different thing entirely. tmux’s command language only runs in three places:

1. Inside ~/.tmux.conf (read on tmux startup).
2. After Ctrl+a : (the tmux command prompt — runs one command interactively).
3. Inside scripts that drive tmux (tmux set -g mouse on from bash works because you prefix with tmux).

Fix. Pick the right context:

• To make a config change permanent: edit ~/.tmux.conf, save, then either Ctrl+a r to reload (if you’ve added the reload binding from Stage 3), or tmux kill-server and start fresh.
• To test one change interactively: press Ctrl+a : to open the tmux command prompt, then type set -g mouse on (without tmux), press Enter.
• To run a tmux command from bash: prefix it with tmux. For example, tmux set -g mouse on works at the bash prompt.

This is the single most common new-user mistake. The three contexts (bash, tmux config, tmux command prompt) take a beat to get used to.

---

❌ no server running on /tmp/tmux-0/default

Symptom. You run tmux ls and see:

no server running on /tmp/tmux-0/default

Cause. This is not an error. It’s tmux telling you there are no sessions running — there’s no tmux server process active.

Fix. Nothing to fix. Start a session:

tmux new -s drill

and tmux ls will work normally from then on.

---

❌ Prefix key (Ctrl+a) doesn’t do anything

Symptom. You press Ctrl+a d to detach (or any other prefix command) and nothing happens. The character \x02 might appear in your shell, or the keystroke gets eaten somewhere.

Cause. Something in your stack is intercepting Ctrl+a before tmux sees it. Most common culprits:

• The terminal app has a custom binding on Ctrl+a (some have “back one character” or similar).
• An IDE or extension grabs Ctrl+a (VS Code’s integrated terminal can do this).
• You’re inside a nested tmux session and the inner one is waiting for its own Ctrl+a.
• You’re not in tmux at all (no status bar at the bottom).

Fix:

1. Confirm you’re in tmux: echo $TMUX should print a path. If it’s blank, you’re not in a session.

2. Confirm the status bar is visible at the bottom of the terminal.

3. Check your terminal app’s keybindings. iTerm2: Preferences → Keys. Termius: Settings → Keyboard. Remove or remap any Ctrl+A (or Ctrl+B on vanilla tmux) bindings that conflict.

4. If using VS Code’s integrated terminal, Settings → Terminal › Integrated: Send Keybindings to Shell = true (or send your prefix specifically).

5. As a workaround, change the prefix. The iSu standard is already Ctrl+a — set in ~/.tmux.conf like this:

   unbind C-b
   set -g prefix C-a
   bind C-a send-prefix

   Ctrl+a does collide with bash’s “go to start of line” — that’s a known trade-off. If that bothers you, pick something else (e.g. C-Space) and update accordingly. Whatever you pick, this tutorial’s keystrokes assume Ctrl+a, so substitute mentally.

---

❌ Mouse wheel scrolls the shell instead of tmux history

Symptom. Inside tmux, scrolling the mouse wheel sends arrow-key sequences to the shell instead of scrolling back through output.

Cause. Either mouse on isn’t set, or you need to enter copy mode to scroll history.

Fix:

1. Add set -g mouse on to ~/.tmux.conf, reload (Ctrl+a r or restart tmux).
2. With mouse on, the wheel scrolls. tmux automatically enters copy mode when you scroll up.
3. Without mouse on (or as an alternative), enter copy mode manually: Ctrl+a [. Then scroll with arrow keys, Page Up/Page Down, or Ctrl+u/Ctrl+d. Press q to exit copy mode.

See Stage 2 — Copy mode for the full workflow.

---

❌ Selection doesn’t reach my Mac (or iPad) clipboard

Symptom. You select text in copy mode with v and y, but Cmd+V (or paste in another app on iPad) gives you old content — your tmux selection didn’t reach the system clipboard.

Cause. Either the set-clipboard option isn’t on, or your terminal app doesn’t support OSC 52 (the protocol tmux uses to talk to the system clipboard), or — for iPad — Termius’s OSC 52 setting is off.

Fix:

1. Add to ~/.tmux.conf:

   set -g set-clipboard on

   Reload (Ctrl+a r).

2. Confirm your terminal supports OSC 52:

   • iTerm2 — yes, on by default.
   • Ghostty — yes, on by default.
   • Terminal.app — yes on macOS Sonoma+.
   • Termius (iPad) — yes, but must be enabled. Settings → Terminal → Sequences → enable OSC 52.

3. If you’ve been using the legacy pbcopy/pbpaste workaround, you can drop it once set-clipboard on is working. The simple y keystroke is enough.

4. Test it. In copy mode, v to select a few characters, y to copy. Then in any other app: paste. If it still fails, try Ctrl+a ? and confirm your copy-selection-and-cancel binding is wired (Stage 3 covers the recommended bindings).

---

❌ Pasted text gets garbled or runs as commands

Symptom. You paste a block of text into a tmux pane and it executes line by line, or characters get interpreted as keystrokes (e.g. n becomes “next window”).

Cause. Two possibilities. The shell is auto-running each line on Enter. Or you’re pasting into a tmux pane while it’s in copy mode, which interprets keystrokes as commands.

Fix:

• Confirm you’re not in copy mode. If q exits something, you were in copy mode. Press q first, then paste.
• Use bracketed paste. Modern terminals support bracketed paste (the terminal tells the shell “this is a paste, don’t interpret”). If your shell doesn’t honour it, look into a wrapper like bracketed-paste-magic for zsh.
• For multi-line content into vim/nvim, enter insert mode with i, then paste. For pasting into a shell as a command block, consider using a heredoc or saving to a file.

---

❌ Auto-attach overrides what I want to do

Symptom. Your ~/.bashrc has logic that auto-attaches you to a tmux session on SSH login (or new terminal), but right now you specifically want a fresh shell to do something else.

Cause. The auto-attach logic is doing exactly what it was told to do.

Fix. Use the NO_AUTO_TMUX escape hatch (already wired into the recommended twork alias from Stage 3):

NO_AUTO_TMUX=1 ssh production-server-01

Or for a local shell:

NO_AUTO_TMUX=1 bash

The twork alias from Stage 3 builds this in. If your ~/.bashrc auto-attaches, make sure it checks $NO_AUTO_TMUX early and skips when set:

# Skip auto-attach if explicitly disabled
if [ -n "$NO_AUTO_TMUX" ]; then
    return
fi
# ... auto-attach logic here

---

❌ “session not found” or “duplicate session”

Symptom. tmux attach -t nafbi gives can't find session: nafbi — but you swear you started it.

Or: trying to start a session gives duplicate session: nafbi.

Cause. Different machines and different users have separate tmux servers. A session you started on production-server-01 isn’t visible from your Mac. A session you started as root isn’t visible to your normal user (and vice versa).

Fix:

• Run tmux ls on the same machine, as the same user you started the session under.
• For “duplicate session,” the session already exists — attach to it instead: tmux attach -t nafbi.
• If you want a fresh session with the same name, kill the old one first: tmux kill-session -t nafbi, then tmux new -s nafbi.

The startup-script pattern from Stage 4 handles this idempotently — run the same script twice, second run reattaches.

---

❌ Session got “stuck” — keys do nothing

Symptom. A pane stops responding to input. Typing does nothing. The cursor doesn’t move.

Cause. Usually one of:

• A long-running command is blocking and consuming output.
• Ctrl+s was pressed (XOFF — pauses terminal output).
• The pane’s process exited but tmux is showing the dead shell.

Fix:

1. Press Ctrl+q (XON) — undoes a stray Ctrl+s.
2. If still stuck, switch panes (Ctrl+a →) and run ps -ef | grep tmux to find the misbehaving process.
3. Kill the stuck pane: Ctrl+a x. tmux will ask for confirmation.
4. Worst case, kill the whole session: tmux kill-session -t SESSION from another shell.

---

❌ Status bar is missing or looks wrong

Symptom. No status bar at the bottom, or it’s shown but with corrupted characters / wrong colours.

Cause. Either the status bar is disabled (status off somewhere), or your terminal’s TERM setting doesn’t match what tmux expects, or a font issue.

Fix:

1. Check it’s enabled. From inside tmux: Ctrl+a : then set -g status on and Enter.

2. Check TERM. Inside tmux: echo $TERM should be screen-256color, tmux-256color, or similar. If it’s plain xterm, set in ~/.tmux.conf:

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

3. Corrupted glyphs usually mean a terminal font that lacks the box-drawing characters tmux uses. Switch to a font like JetBrains Mono, Fira Code, or Menlo.

---

❌ TPM plugins aren’t loading

Symptom. Added plugins to ~/.tmux.conf and pressed Ctrl+a I, but nothing happens — or the plugins aren’t taking effect.

Cause. Most often: the run '~/.tmux/plugins/tpm/tpm' line isn’t at the bottom of ~/.tmux.conf. Or TPM itself isn’t installed.

Fix:

1. Confirm TPM is cloned:

   ls ~/.tmux/plugins/tpm

   If empty/missing:

   git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

2. Confirm run '~/.tmux/plugins/tpm/tpm' is the last line of ~/.tmux.conf. TPM needs to load after everything else.

3. Reload config (Ctrl+a r or restart tmux), then press Ctrl+a I (capital I) to install. TPM downloads each plugin into ~/.tmux/plugins/.

4. If still failing, check ~/.tmux/plugins/tpm/scripts/install_plugins.sh exists and is executable.

---

❌ “Server running” but nothing visible / can’t attach

Symptom. tmux ls shows sessions exist, but tmux attach opens a session that looks empty or unresponsive.

Cause. A previous client is still attached and tmux is sharing the screen across both. Or the session has only dead/exited shells.

Fix:

• See who’s attached: tmux list-clients. If multiple, that’s why the screen is being shared.
• Force-detach all other clients on attach: tmux attach -d -t SESSION (the -d flag detaches everyone else first).
• If the session is genuinely empty/broken, tmux kill-session -t SESSION and start a fresh one.

---

❌ Window or pane dies immediately on creation

Symptom. You create a new window/pane and it instantly closes.

Cause. The shell or program in the new window is exiting on startup. Usually a typo in ~/.bashrc, or a set -e style script aborting.

Fix:

1. Run the new window’s command manually in a regular shell to see the actual error.

2. Check ~/.bashrc and ~/.bash_profile for syntax errors:

   bash -n ~/.bashrc

3. If a startup script (Stage 4 pattern) is sending keys to a shell that just died, the keys go nowhere. Add sleep 1 or check process state before sending keys.

---

🆘 Still stuck?

A few last-resort steps:

• Show all current bindings: Ctrl+a ? lists every key in the active session. Useful for spotting conflicts.
• Show config in effect: Ctrl+a : then show-options -g lists every global option’s current value. Same with show-window-options -g for window options.
• Start with a clean config to isolate: tmux -f /dev/null new-session ignores ~/.tmux.conf. If the issue disappears with a blank config, your config is the cause.
• Restart the tmux server: tmux kill-server blows everything away. Heavy hand, but a guaranteed clean slate. (Save anything you care about first.)

If a problem isn’t on this page, tmux’s man page is dense but complete. man tmux on the server.

---

🔗 Related

• Back to the Cheat Sheet
• The recommended config: Stage 3 — Customisation
• Or the tmux Tutorial landing page