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:

   bash

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

2. •

   Check directory permissions:

   bash

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

3. •

   If still failing, check tmux server is responsive:

   bash

   # From inside tmux
   tmux refresh-client
   

4. •

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

   bash

   # 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:

   bash

   echo $TMUX
   # Shows socket path and server PID
   

2. •

   Send SIGUSR1 only to that specific PID:

   bash

   # 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):

   bash

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

   This directory persists across reboots on systemd systems.

2. •

   Custom socket location:

   bash

   # 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