Client cannot reach the tmux server socket: stale socket versus exit-empty policy

Question

tmux is a client/server program. Each client command connects to a long-lived per-user server over a local Unix domain socket, by default inside a tmux-<uid> directory under the temporary directory and overridable with TMUX_TMPDIR. No name resolution and no certificate validation occur on that path, so resolver and TLS diagnostics do not apply to a client that cannot reach the server.

The failure condition is a client that finds no usable server socket: none is running, or the socket is stale, inaccessible, or owned by another user. A different TMUX_TMPDIR between shells yields a separate server, which can resemble a vanished session. Exact message wording and exit status vary by release, so the installed manual page is the reference.

The unresolved decision is server lifetime. The exit-empty option governs whether the server exits once the last session ends, and that choice changes startup latency and how an absent-server condition surfaces in scripts.

Should automation treat an absent server as a normal state to create on demand, or depend on a persistent server kept alive by exit-empty off?
How can a stale socket from an unclean shutdown be distinguished from a server that is simply not running, given version-dependent message text?
Does the answer change when clients run under different users or TMUX_TMPDIR values?

Tasadduq Burney · Answer

Answer in a nutshell
When a tmux client says it can’t reach the server socket, the two scenarios are:

Stale socket – the socket file still exists but no tmux process is listening on it. The client will fail until you delete the file or a new server is started.
  Expected absence because exit‑empty is on – the server exits as soon as the last session ends, so the socket file is removed. A new client will automatically start a fresh server, which is normal.

Follow the steps below to determine which case applies and to recover.
Step‑by‑step troubleshooting

Locate the socket path```bash
# Default path if TMUX_TMPDIR is unset
SOCKET_DIR=${TMUX_TMPDIR:-$TMPDIR}/tmux-$(id -u)
SOCKET=$(ls -1 $SOCKET_DIR | head -n1)  # usually a single file
SOCKET_PATH=$SOCKET_DIR/$SOCKET
```
  Check if a tmux server is running```bash
pgrep -u $(id -u) -x tmux
```If this returns nothing, no server process is alive.
  Verify socket liveness```bash
# Is the file a socket?
if [ -S "$SOCKET_PATH" ]; then
  echo "Socket file exists"
else
  echo "No socket file"
fi

# Is any process listening on it?
ss -lx | grep $(basename "$SOCKET_PATH")
```If ss shows no listener, the socket is stale.
  Check the exit‑empty setting```bash
tmux show-options -gs exit-empty
```Output will be on or off. If it is on and the socket file is missing, the absence is expected.
  Clean up a stale socketOnly do this after confirming there is no running tmux process:```bash
rm -f "$SOCKET_PATH"
```Then run a tmux command such as tmux ls – a new server will start automatically.
  Verify behavior after detaching the last sessionStart a session, detach it, and run tmux ls again. If the server persists, exit-empty is off; if the session list disappears, it is on.
  Consider TMUX_TMPDIR differencesRunning under a different TMUX_TMPDIR or a different UID creates a separate socket namespace. Ensure all related processes share the same TMUX_TMPDIR value and UID.

Why the distinction matters

A stale socket can prevent any client from reconnecting until it is removed, even if a server is running elsewhere.
  When exit-empty is on, scripts that expect a persistent server will see a brief latency spike each time a new server is spawned.
  Running clients under different users or with different TMUX_TMPDIR values will never see each other’s sessions unless the same namespace is used.

One diagnostic detail we still need
To confirm the tmux version you’re using, run tmux -V. The exact wording of the “cannot connect” message and the default value of exit-empty can vary slightly between releases.

Client cannot reach the tmux server socket: stale socket versus exit-empty policy

1 answer

Answer in a nutshell

Step‑by‑step troubleshooting

Why the distinction matters

One diagnostic detail we still need

Your perspective belongs here.

0 question comments