Fixing xterm-ghostty: unknown terminal type

If you use Ghostty as your terminal on macOS and SSH into remote Linux servers, you’ve probably seen this:

root@server:~# clear
'xterm-ghostty': unknown terminal type.

Or this:

missing or unsuitable terminal: xterm-ghostty

This happens to everyone who uses Ghostty with remote servers. Here’s why it happens and how to fix it properly.

Why This Happens#

Ghostty ships with its own terminfo entry called xterm-ghostty. When you open a terminal, Ghostty sets TERM=xterm-ghostty in your local shell. When you SSH into a remote server, that TERM value gets forwarded. The remote server then looks up xterm-ghostty in its terminfo database – and finds nothing, because xterm-ghostty is not in any standard Linux distribution yet.

Commands like clear, vim, tmux, and htop all rely on terminfo to know how to talk to your terminal. No terminfo entry means broken output.

The Trap: ssh-terminfo Makes It Worse#

Ghostty has a built-in feature called ssh-terminfo that tries to automatically install the xterm-ghostty terminfo on remote hosts before connecting. On paper this sounds like the right fix. In practice it causes a worse problem.

The feature wraps your ssh command as a shell function. Every time you SSH, it tries to run tic on the remote host to install the terminfo. For servers behind a ProxyJump, air-gapped servers, or servers with restricted environments, the install process partially succeeds – returns exit 0 – but the terminfo is not actually usable. The function then assumes success and sets TERM=xterm-ghostty for the session anyway. You land on the server with a broken terminal.

Worse, this shell function override happens after your ~/.ssh/config is read, so any SetEnv TERM=xterm-256color you put there gets silently overridden.

This is the config that enables the broken behavior:

shell-integration-features = ssh-env,ssh-terminfo

The Actual Fix#

There are two parts. Fix them both.

1. Disable ssh-terminfo in Ghostty config#

Find your Ghostty config file. On macOS it is usually at:

~/Library/Application Support/com.mitchellh.ghostty/config

Change your shell-integration-features line to remove ssh-env and ssh-terminfo:

shell-integration-features = cursor,title,path

Reload the config with Cmd+Shift+, or fully quit and reopen Ghostty.

Verify the ssh shell function is no longer overriding TERM:

echo $GHOSTTY_SHELL_FEATURES
# should not contain ssh-env or ssh-terminfo

2. Set TERM globally in ~/.ssh/config#

Add SetEnv TERM=xterm-256color to your global Host * block. This tells the remote server to use xterm-256color which has been in every Linux terminfo database for over 20 years.

One important rule: Host * must be at the bottom of your ~/.ssh/config. SSH reads the file top to bottom and the first match wins for each option. If Host * is at the top, it overrides all your specific host blocks.

# specific hosts first
Host myserver
    HostName 10.0.0.1
    User deploy

# global defaults last
Host *
    User root
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
    SetEnv TERM=xterm-256color

After both changes, SSH into any server and run clear – it works.

Why Not Just Push Terminfo to Every Server?#

The official Ghostty docs suggest running this on each remote host:

infocmp -x xterm-ghostty | ssh user@server -- tic -x -

This works for servers you own and access regularly. It is not practical if you manage dozens or hundreds of servers, have air-gapped hosts with no outbound connectivity, or SSH into servers you do not control.

The xterm-256color approach trades a small amount of Ghostty-specific terminal features for universal compatibility. In practice you keep full 256 color support, all standard cursor sequences, and everything TUI apps need. The only things you lose are a few Ghostty-specific extensions that most remote workflows do not use anyway.

Summary#

Two files to get right, and the problem never comes back.