Troubleshooting Tmux 'Session Not Found' and Connection Failures

The most common frustration for tmux users is returning to a remote server only to find error: session not found, despite being certain work was running. This usually happens not because the session died, but because the communication bridge between the tmux client (your terminal) and the tmux server (the background process) has broken.

This guide helps you diagnose why you cannot reconnect to your existing sessions and provides steps to recover them without killing your processes.

Identifying the Symptoms

Before running commands, identify the specific behavior you are experiencing:

Symptom	Likely Cause
tmux ls returns no output or 'no server is not running'	The Unix socket file is missing or permissions are incorrect.
tmux attach hangs or freezes	A 'ghost' process exists from a previously interrupted SSH connection.
New sessions fail to open or crash	System process limits (ulimit) have been reached.
'Session not found' for a specific name	The TMUX_SOCK environment variable is pointing to the wrong path.

Step 1: Verify the Socket Directory

tmux uses Unix domain sockets to communicate between the client and server. By default, these are stored in /tmp/tmux-UID/. If this directory was deleted by a system cleanup script or permissions changed, the client cannot find the server.

Run the following command to check if the directory exists for your user:

ls -la /tmp/tmux-$(id -u)/

If the directory is missing, the tmux server process has likely terminated (possibly due to a reboot or a manual kill). If it exists, ensure your user has read/write permissions on the socket file inside it.

Step 2: Check for Orphaned Server Processes

If tmux ls fails but you know your processes are running, the server might be alive but the socket is unreachable. This often happens after an SSH session drops abruptly.

Check for active tmux server processes using the process list:

ps -fl | grep tmux

If you see a process but tmux attach fails, you can attempt to force a connection by pointing directly to the socket if you know the location:

tmux -S /tmp/tmux-$(id -u)/default attach

Step 3: Investigate Resource Limits

If the tmux server is running but refuses to open new windows or split panes, you may have hit the system's process limit per user. Each window and pane in tmux counts as a separate process.

Check your current process limit:

ulimit -u

If the value is low (e.g., 1024) and ps -U shows a count close to that, you will need to increase the limit in /etc/security/limits.conf or close unnecessary background tasks.

Recovery and Fixes

If you have identified the cause, follow these actions to restore your environment:

• If the socket is missing: The server is gone. You cannot recover the session state. You must start a new session: tmux new -s session_name.
• If the session is 'hung': Kill the specific client process associated with the hung terminal, not the server. Use tmux kill-client -t session_name to safely detach the client, then try reattaching.
• If using custom sockets: If you used the -S flag to create your session, you must use the same -S flag to attach: tmux -S /path/to/my/socket attach.

Warning: Never run killall tmux unless you are prepared to lose all running work in all tmux sessions. This terminates the server process and immediately shuts down all unsaved data and programs within tmux windows.