How to fix 'failed to connect to server' error in tmux?

Detailed Explanation

The "failed to connect to server: Connection refused" error occurs when the tmux client cannot establish a connection with the tmux server. Understanding how tmux's client-server architecture works helps troubleshoot this issue.

Understanding tmux's Client-Server Architecture

tmux operates using a client-server model:

• The server manages sessions, windows, and panes
• The client connects to the server to display and interact with these sessions
• Communication happens through a socket file, typically located in /tmp/tmux-$UID/

When you run a tmux command like tmux attach, the client tries to connect to this socket. If the server isn't running or the socket is inaccessible, you'll see the connection refused error.

Common Causes and Solutions

Let's explore the most common causes of this error and how to fix them:

1. No tmux server running

This is the most common cause. If you try to attach to a session but no tmux server is running, you'll get this error. The solution is simple:

# Start a new tmux server and session
tmux new

If you want to check if any tmux servers are running:

ps aux | grep tmux

2. Stale socket files

If tmux wasn't shut down properly (e.g., due to a system crash), it might leave behind stale socket files that block new connections. Check for these files and remove them:

# Check for tmux socket files
ls -la /tmp/tmux*

# Remove socket files (replace $UID with your user ID)
rm /tmp/tmux-$UID/default

# Or remove all socket files for your user
rm /tmp/tmux-$UID/*

After removing the stale socket files, try starting tmux again.

3. Permission issues

If the /tmp directory or the tmux socket directory has incorrect permissions, you may encounter connection issues:

# Check permissions on /tmp
ls -ld /tmp

# Check permissions on the tmux socket directory
ls -ld /tmp/tmux-$UID

# Fix permissions if needed
chmod 1777 /tmp  # Requires root access
mkdir -p /tmp/tmux-$UID
chmod 700 /tmp/tmux-$UID

The /tmp directory should have permissions 1777 (sticky bit set), and your tmux socket directory should be 700 (readable, writable, and executable only by you).

4. Custom socket location

If you or your system has configured tmux to use a non-default socket location (via TMUX_TMPDIR environment variable or the -S option), the client may be looking in the wrong place:

# Check if TMUX_TMPDIR is set
echo $TMUX_TMPDIR

# Connect using a specific socket path
tmux -S /path/to/socket attach

# Or start a new server with a specific socket
tmux -S /path/to/socket new

5. Version mismatch

If the tmux client and server versions are incompatible, you might get a connection error. Check your tmux version:

tmux -V

If you're using multiple versions of tmux (e.g., one system-installed and one manually compiled), ensure you're using the correct one:

# Find all tmux executables
which -a tmux

# Use the full path to the desired version
/path/to/specific/tmux new

Debugging the Connection Issue

For more difficult cases, you can enable verbose logging to get more information:

# Run tmux with verbose logging
tmux -v new
tmux -v attach

You can also try to determine if any other process is using the tmux socket:

fuser -v /tmp/tmux-$UID/default

# Add to ~/.bashrc or ~/.zshrc
alias tmux-reset="rm -rf /tmp/tmux-$UID && tmux new -d && echo 'tmux server restarted'"

# Start tmux with a named socket
tmux -L mysocket new -s mysession

# Connect to that specific socket
tmux -L mysocket attach -t mysession

# List sessions on that socket
tmux -L mysocket list-sessions