fixing-tmux-socket-issues

name	Fixing tmux Socket Issues
description	This skill repairs tmux socket connection errors when the socket directory is deleted while tmux is running. Use this when you see "error connecting to /private/tmp/tmux-UID/default (No such file or directory)" while tmux sessions are still active.
allowed-tools	["Bash","Read"]

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