The messages
All of these have the same cause. Each program reports it in its own way:
| Program | Output |
|---|---|
nano, htop | Error opening terminal: xterm-256color. |
clear | 'xterm-256color': unknown terminal type. |
tput | tput: unknown terminal "xterm-256color" |
tmux | missing or unsuitable terminal: xterm-256color |
less | WARNING: terminal is not fully functional |
A different message, TERM environment variable not set., means the session has no terminal at all, for example a command run with ssh server clear. Add -t in that case. See -t and -T.
Confirm the cause
On the server, after logging in:
echo "$TERM"
infocmp "$TERM" > /dev/null; echo $?A failure looks like this:
infocmp: error: no match in terminfo database for terminal type "xterm-256color"Newer terminals often bring a TERM name of their own, and many servers do not have it. A missing xterm-256color is rarer, and points to a minimal image or a container where the terminfo files were left out.
Fix 1: copy the entry to the server
Run this on your own machine, in the terminal that has the problem. No root is needed:
infocmp -x | ssh user@server -- tic -x -infocmp -x prints the entry for your current TERM, and tic compiles it on the server into ~/.terminfo. You keep all the features of your terminal, and the fix survives future logins. Warnings from tic are usually harmless, so test it after a new login:
clear
tput colsIt applies only to that one user. To make it work for everyone, including root under sudo, install it from a file as root, which writes to a system folder:
infocmp -x > term.ti
scp term.ti user@server:
ssh -t user@server 'sudo tic -x term.ti'If tic on the server answers with Illegal character errors, the infocmp on your Mac is too old. This happens before macOS Sonoma: use the one from Homebrew's ncurses package.
Fix 2: send a common name
Use this when you cannot write anything on the server, such as a shared account or a device. For one connection:
ssh -o SetEnv=TERM=xterm-256color user@serverOr permanently for that host, in ~/.ssh/config:
Host legacy
HostName 203.0.113.10
SetEnv TERM=xterm-256colorOther per-host options are in these ssh config file examples.
The server does not need any AcceptEnv line for this, since TERM is the exception to that rule. It needs OpenSSH 8.7 or later on your client. On older clients, set it for the command:
TERM=xterm-256color ssh user@serverYour session then runs as a plain xterm. Almost everything works, but features specific to your terminal, such as styled underlines, do not.
If you are already logged in, this works for the current shell:
export TERM=xterm-256colorFix 3: install the package
Distributions ship extra entries in a separate package. On Debian and Ubuntu:
sudo apt install ncurses-termIn Debian 13 this added many entries, but not those of some newer terminals, which come in packages of their own. On Alpine, look for ncurses-terminfo. For a terminal the package does not cover, use fix 1.
Avoid hiding the problem in your shell config
Setting TERM unconditionally in ~/.bashrc breaks correct values on every future login, including inside tmux. If you must set it there, do it only when the current value is unknown:
infocmp "$TERM" >/dev/null 2>&1 || export TERM=xterm-256colorQuestions
Which TERM value works on most servers?
xterm-256color is on almost every current Linux server. On very old or minimal systems, xterm or vt100 are safer.
Do I need root to fix unknown terminal type?
No. infocmp -x | ssh user@server -- tic -x - installs the entry in ~/.terminfo for your user. Root is needed only to install it for every user.
Why does tmux say missing or unsuitable terminal?
The server has no terminfo entry for your TERM. The same fixes apply: copy the entry, or connect with a common name such as xterm-256color.