tmux Said “Not a Terminal.” The Terminal Was Fine

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 terminal

The 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-sessions

All 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 $TERM incorrect?
  • 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 test

It worked.

This command changes two things:

  • -L selects a separate, named server socket rather than the default one.
  • -f /dev/null starts 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 test

That 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 -V

reported 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/default

My 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/tmux

Then we connected it explicitly to the original server:

~/.local/opt/tmux-3.5a/bin/tmux \
  -S /private/tmp/tmux-501/default \
  attach-session -t COCKPIT

It 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/default

The path breaks down as follows:

  • /private/tmp is the macOS temporary directory that /tmp points to.
  • tmux-501 is tmux’s directory for user ID 501.
  • default is 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-sessions

2. Compare the client and server versions

tmux -V
tmux 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 test

If 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-session

This 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.