How a misleading error sent us chasing terminal settings—and how we recovered the existing sessions without restarting their server.
I had just updated Ghostty. Then I opened a terminal, typed tmux, and got:
open terminal failed: not a terminalThe timing made Ghostty the obvious suspect. Everything had worked before the update, and now tmux refused to open.
But the terminal was fine. The breakthrough came when we stopped looking only at the terminal and started looking at which tmux server the client was talking to.
The confusing part: my sessions were still there
Although attaching failed, listing sessions worked:
tmux list-sessionsAll my existing sessions appeared, including projects with multiple windows and running processes.
That was reassuring, but also confusing: if tmux could find my sessions, why couldn’t it open one?
The distinction matters. Listing sessions only requires communication with the server. Attaching also requires the server to accept and initialize the client’s terminal.
One can work while the other fails.
The false leads
We initially investigated terminal configuration:
- Was Ghostty’s terminfo entry missing?
- Was
$TERMincorrect? - Was a shell plugin interfering?
- Did the shell lack a controlling terminal?
- Had the Ghostty update introduced a PTY regression?
Those were hypotheses—not established causes. Several were stated far too confidently during the troubleshooting.
Changing Ghostty’s terminal type to xterm-256color did not help. Neither did upgrading the tmux client, first to a newer stable release and then to a development build.
We also made an important diagnostic mistake: running terminal checks through a coding agent’s command runner. Those commands ran without an interactive TTY, so their results did not describe the actual Ghostty shell.
The useful checks had to run directly in Ghostty:
tty[ -t 0 ] && echo "stdin: tty"[ -t 1 ] && echo "stdout: tty"They showed a valid terminal device and confirmed that stdin and stdout were TTYs.
Further checks succeeded too: opening the terminal device, reading its attributes, querying its size, and passing its file descriptor between processes.
There was no evidence supporting the theory that Ghostty had stopped providing a usable terminal.
The turning point: a separate server
The most useful test was also one of the simplest:
tmux -L "ghostty-test-$$" -f /dev/null new-session -s testIt worked.
This command changes two things:
-Lselects a separate, named server socket rather than the default one.-f /dev/nullstarts that server without loading my tmux configuration.
It did not restart or modify the server holding my existing sessions.
Next, we repeated the experiment with my normal configuration:
tmux -L "ghostty-config-test-$$" \ -f "$HOME/.config/tmux/tmux.conf" \ new-session -s testThat worked too, apart from two unrelated configuration warnings.
At that point, the problem was much narrower:
The current client could start and attach to a fresh server in Ghostty—even with my configuration. Attaching to the existing server was what failed.
There were two different tmux versions
Running:
tmux -Vreported the version of the client executable on disk.
It did not tell us the version of the server that had been keeping my sessions alive.
To inspect that server, we ran:
tmux display-message -p \ 'server_pid=#{pid} server_version=#{version} socket=#{socket_path}'The important parts of the result were:
server_version=3.5a socket=/private/tmp/tmux-501/defaultMy existing server was still running tmux 3.5a. Meanwhile, after the troubleshooting upgrades, the client reported next-3.9.
Updating an installed executable does not replace a process that is already running. The old server had continued managing my sessions throughout the upgrades.
That persistence is useful—but it also means “which tmux version am I using?” can have two answers.
Recovering the old sessions
Starting a fresh server was a useful diagnostic, but it was not the solution I needed. I wanted access to the work already running in my old sessions.
Rather than kill the original server, we built a separate tmux 3.5a client and installed it alongside the newer version:
~/.local/opt/tmux-3.5a/bin/tmuxThen we connected it explicitly to the original server:
~/.local/opt/tmux-3.5a/bin/tmux \ -S /private/tmp/tmux-501/default \ attach-session -t COCKPITIt worked. My old session opened.
No server restart. No deleted sessions. No need to recreate the running work.
This strongly implicated compatibility between the newer clients and that particular older server. We did not establish the precise internal reason the terminal initialization failed, so claiming a specific protocol bug—or a Ghostty regression—would go beyond the evidence.
Where did that socket path come from?
We did not guess it. The running server reported it:
tmux display-message -p '#{socket_path}'On this machine, the result was:
/private/tmp/tmux-501/defaultThe path breaks down as follows:
/private/tmpis the macOS temporary directory that/tmppoints to.tmux-501is tmux’s directory for user ID501.defaultis the default server socket name.
The -S option tells a client to use an exact socket path. That made it explicit that the separately installed 3.5a client should connect to the original server.
Your own path may differ. Ask the server rather than copying this example blindly.
A shorter troubleshooting path
If you encounter the same error while existing tmux sessions are still running, this is the sequence I would follow.
1. Preserve the existing server
Do not start with tmux kill-server. It terminates the sessions you may be trying to recover, putting their running work at risk.
First, check whether they are still available:
tmux list-sessions2. Compare the client and server versions
tmux -Vtmux display-message -p 'server=#{version} socket=#{socket_path}'Different versions do not automatically prove incompatibility, but they are an important clue.
3. Test a fresh, isolated server
Run this directly in your terminal, outside tmux:
tmux -L "tty-test-$$" -f /dev/null new-session -s testIf it opens, type exit to close the test session.
Success shows that a basic interactive tmux session works in that terminal. It shifts attention toward the existing server or its configuration.
4. Test the normal configuration separately
Start another named server with your usual configuration file. This helps distinguish configuration problems from problems specific to the original running server.
5. Try a matching client
If the old server is running a different version, install a matching client separately and use it to attach through the server’s reported socket path:
/path/to/matching/tmux -S /path/to/original/socket attach-sessionThis avoids replacing or restarting the server during recovery.
The lesson
The Ghostty update was a compelling clue because it happened immediately before the failure. But timing alone did not establish the cause.
The decisive evidence was:
- Terminal checks passed.
- A fresh tmux server worked.
- A fresh server with my normal configuration also worked.
- The original server was running an older version.
- A matching client successfully attached to it.
The error said “not a terminal.” The practical fix was not to change the terminal—it was to use a client that could successfully attach to the server already holding my work.