Fixing tmux Socket Issues

Repair tmux socket connection errors without killing your running sessions.

What This Skill Does

• Diagnoses tmux socket connection failures
• Recreates missing socket directories
• Signals tmux server to recreate socket files
• Verifies manual save/restore functionality
• Preserves all running sessions and processes

When to Use This Skill

Symptoms:

• Error:

  error connecting to /private/tmp/tmux-UID/default (No such file or directory)

• tmux list-sessions

  fails but you're inside a working tmux session

• $TMUX

  environment variable is set but socket file doesn't exist
• tmux-resurrect manual save fails but automatic saves may appear to work

Common causes:

• System

  /tmp

  directory cleanup
• System updates or reboots
• Manual deletion of temp directories

How tmux Sockets Work

tmux uses a UNIX domain socket for client-server communication. The socket path format is:

/private/tmp/tmux-UID/default

Where

UID

is your user ID (e.g.,

504

).

Why sessions survive socket deletion:

• The tmux server process keeps the socket open as a file descriptor
• Existing connections continue to work
• New connections fail because the filesystem path is gone
• The server is alive but unreachable by new clients

Prerequisites

1. Active tmux session - You must be inside a running tmux session
2. Shell access - Ability to run commands (inside or outside tmux)
3. Permissions - Ability to create directories in

   /private/tmp

   or

   /tmp

Diagnosis Steps

Step 1: Verify the Problem

Check if you're in tmux but the socket is missing:

# Check if TMUX is set (confirms you're in a session)
echo $TMUX
# Example output: /private/tmp/tmux-504/default,1632,1

# Try to list sessions (will fail if socket is missing)
tmux list-sessions
# Expected error: error connecting to /private/tmp/tmux-504/default (No such file or directory)

# Verify socket directory doesn't exist
ls -la /private/tmp/tmux-*/
# Expected error: No such file or directory

If all three conditions are true (TMUX set, list-sessions fails, directory missing), proceed with the fix.

Step 2: Check Last Successful Save

Verify when tmux-resurrect last successfully saved:

ls -lh ~/.tmux/resurrect/last
stat ~/.tmux/resurrect/last

Note the timestamp. If it's old (before the socket disappeared), automatic saves are likely also failing.

Repair Steps

Step 1: Recreate Socket Directory

Extract the socket directory path from

$TMUX

:

# Show full TMUX path
echo $TMUX
# Example: /private/tmp/tmux-504/default,1632,1

# The directory is everything before '/default'
# For example: /private/tmp/tmux-504

Create the directory with correct permissions:

# Replace '504' with your actual UID from $TMUX
mkdir -p /private/tmp/tmux-504
chmod 700 /private/tmp/tmux-504

Permission requirements:

• Directory must be owned by your user
• Permissions must be

  700

  (drwx------) for security

Step 2: Find tmux Server PID

The tmux server is the oldest tmux process:

# List all tmux processes
ps aux | grep tmux | grep -v grep

Look for the process with:

• Oldest start time
• Command

  tmux

  (not

  tmux attach

  )
• Usually the lowest PID

Example output:

jonathan  1632  1.1  0.0 435326336  5184  ??  Ss  1Nov25  102:36.11 tmux
jonathan 22779  0.0  0.0 435309312   624 s077 S+  1Nov25    0:00.05 tmux attach -t 3

In this example, PID

1632

is the server (started Nov 25, command is just

tmux

).

Step 3: Signal tmux to Recreate Socket

Send

SIGUSR1

to the tmux server process:

# Replace 1632 with your actual server PID
kill -SIGUSR1 1632

What this does:

• Signals the tmux server to recreate its socket file
• Does NOT kill or restart tmux
• Reconnects the running server to the filesystem
• Preserves all sessions, windows, and processes

Alternative (if you only run one tmux server):

pkill -USR1 -x tmux

This sends SIGUSR1 to all processes named exactly "tmux".

Step 4: Verify the Fix

Check that the socket file was recreated:

# Socket file should now exist
ls -la /private/tmp/tmux-504/
# Expected: drwx------  3 you  wheel   96 Nov 16 09:18 .
#           srw-rw----  1 you  wheel    0 Nov 16 09:18 default

# tmux commands should now work
tmux list-sessions
# Expected: List of your active sessions

# Test resurrect save script
~/.tmux/plugins/tmux-resurrect/scripts/save.sh

# Verify new save was created
ls -lh ~/.tmux/resurrect/last
# Timestamp should be current

Verification Checklist

After applying the fix:

• Socket directory exists:

  ls -la /private/tmp/tmux-UID/

• Socket file exists with correct permissions:

  srw-rw----

• tmux list-sessions

  succeeds

• tmux list-keys

  succeeds
• Manual resurrect save works:

  ~/.tmux/plugins/tmux-resurrect/scripts/save.sh

• New save file created with current timestamp
• All existing sessions still running
• No processes were killed or restarted

Troubleshooting

Issue: "Permission denied" when creating directory

Cause:

/private/tmp

or

/tmp

may require elevated permissions

Solution:

sudo mkdir -p /private/tmp/tmux-504
sudo chown $(whoami) /private/tmp/tmux-504
chmod 700 /private/tmp/tmux-504

Issue: Socket not recreated after SIGUSR1

Symptoms: Directory exists but socket file still missing after signal

Causes:

1. Wrong PID (sent signal to client, not server)
2. Parent directory permissions incorrect
3. Tmux server in unusual state

Solutions:

1. Verify you got the right PID:

   # The server process should show just "tmux", not "tmux attach"
   ps aux | grep '[t]mux' | grep -v attach
   

2. Check directory permissions:

   ls -ld /private/tmp/tmux-504
   # Should show: drwx------ ... your-username ...
   

3. If still failing, check tmux server is responsive:

   # From inside tmux
   tmux refresh-client
   

4. Last resort - restart tmux server (will lose session state):

   # Save important work first!
   tmux kill-server
   tmux
   

Issue: Multiple tmux servers running

Symptoms:

ps aux | grep tmux

shows multiple "tmux" processes (not "tmux attach")

Cause: Multiple independent tmux servers on different sockets

Solution:

1. Identify which server you're attached to:

   echo $TMUX
   # Shows socket path and server PID
   

2. Send SIGUSR1 only to that specific PID:

   # Don't use pkill, it would signal all servers
   kill -SIGUSR1 <specific_pid>
   

Issue: macOS-specific pgrep syntax error

Symptoms:

pgrep: illegal option -- -

Cause: macOS uses BSD

pgrep

which has different options than GNU

pgrep

Solution:

# BSD (macOS) syntax:
pgrep -o tmux    # oldest process

# Alternative: use ps
ps aux | grep tmux | grep -v grep

tmux-resurrect Keybindings

For reference, the correct keybindings with a custom prefix:

Default prefix:

Ctrl+b

• Save:

  Ctrl+b

  then

  Ctrl+s

• Restore:

  Ctrl+b

  then

  Ctrl+r

Custom prefix:

Ctrl+a

(as in your config)

• Save:

  Ctrl+a

  then

  Ctrl+s

• Restore:

  Ctrl+a

  then

  Ctrl+r

Verify your bindings:

tmux list-keys | grep resurrect

Expected output:

bind-key -T prefix C-r run-shell /path/to/restore.sh
bind-key -T prefix C-s run-shell /path/to/save.sh

Prevention

To reduce the likelihood of this issue:

1. Use XDG_RUNTIME_DIR (Linux):

   # In .bashrc or .zshrc
   export TMUX_TMPDIR=$XDG_RUNTIME_DIR
   

   This directory persists across reboots on systemd systems.

2. Custom socket location:

   # Start tmux with custom socket location
   tmux -S ~/.tmux/socket new-session
   

3. System configuration (requires root):

   • Exclude

     /tmp/tmux-*

     from automated cleanup scripts
   • Configure

     tmpwatch

     or similar tools to skip tmux directories

Best Practices

1. Respond quickly: Fix the socket as soon as you notice the error to avoid confusion
2. Verify timestamps: Always check that saves are actually happening after the fix
3. Document your UID: Note your user ID for faster diagnosis next time
4. Keep sessions active: The fix works because sessions are still running; if you kill tmux first, you'll need to restore from last save
5. Regular saves: Use

   Ctrl+a Ctrl+s

   periodically for important session states

Related Skills

• configuring-neovim - For fixing Neovim session restoration with tmux-resurrect
• working-with-terminals - For understanding terminal multiplexer fundamentals

Understanding tmux-continuum Behavior

Why automatic saves appear to work:

tmux-continuum runs inside the tmux server process using

run-shell

. In some cases:

• Old save timestamps may persist, making it look like saves are working
• The actual save attempts are failing silently
• Check timestamps carefully to confirm saves are current

After fixing:

• Monitor

  ~/.tmux/resurrect/last

  timestamp
• Verify it updates every 15 minutes (or your configured interval)
• First new save confirms the fix worked

Quick Reference

# 1. Create directory
mkdir -p /private/tmp/tmux-$(id -u)
chmod 700 /private/tmp/tmux-$(id -u)

# 2. Find server PID
ps aux | grep '[t]mux' | grep -v attach

# 3. Send signal
kill -SIGUSR1 <server_pid>

# 4. Verify
tmux list-sessions
ls -la /private/tmp/tmux-$(id -u)/

Additional Resources

• tmux man page - SIGUSR1 behavior
• tmux-resurrect documentation
• tmux-continuum documentation