vi, nano or tmux fails with Error opening terminal: xterm-256color
Error opening terminal: xterm-256color.Short answer
A curses program such as vi or nano looks up the terminal named in TERM in the terminfo database. This error means that lookup failed. Run infocmp xterm-256color: if it fails, either TERMINFO points to the wrong place, or the entry is missing and must be installed or replaced with a known TERM.
Fix it fast
1Find out which cause you have
Ask the terminfo tools for the entry directly. This is the same lookup the failing program makes.
echo "$TERM" infocmp xterm-256color | head -n 32Match what you see, then jump to its fix
- 1
infocmp fails, and the TERMINFO variable is set in this shell or in a profile fileTERMINFO points at a directory without the entryFix - 2
TERMINFO is empty and infocmp -D shows the database folders, but none has xterm-256colorThe entry is missing from this machine's databaseFix - 3
echo $TERM prints a name that infocmp also fails to findTERM names a terminal this machine does not knowFix
- 1
What does the error look like?
Error opening terminal: xterm-256color.
Cause 1 of 3
TERMINFO points at a directory without the entry
1Check
ncurses reads TERMINFO first, before ~/.terminfo and the system database. A wrong value hides every correct entry.
echo "$TERMINFO"
echo "$TERMINFO_DIRS"2Fix
Unset the wrong variable for this shell, then remove it from the profile file that sets it.
unset TERMINFO
grep -n 'TERMINFO' ~/.bashrc ~/.profile ~/.zshrc 2>/dev/null3Verify
The lookup now finds the entry.
infocmp xterm-256color | head -n 3Confirmed by man7.org
Cause 2 of 3
The entry is missing from this machine's database
1Check
List the locations ncurses searches, then ask if the entry exists in any of them.
infocmp -D
infocmp xterm-256color2Fix
Copy the entry from a machine that has it and compile it into your own home database with tic, which falls back to ~/.terminfo when the system folder is not writable.
# on a machine that has the entry
infocmp -x xterm-256color > xterm-256color.src
# copy the file over, then on the broken machine
mkdir -p ~/.terminfo
tic -x -o ~/.terminfo xterm-256color.src3Verify
Open the editor again.
infocmp xterm-256color | head -n 3
nano --versionConfirmed by man7.org
Cause 3 of 3
TERM names a terminal this machine does not know
1Check
infocmp with no argument uses the TERM variable as the terminal name, so it tells you whether the current value resolves.
echo "$TERM"
infocmp | head -n 32Fix
Set TERM to a name that exists here, for this session or in your shell profile.
export TERM=xterm-256color3Verify
The lookup and the editor work.
infocmp | head -n 3Confirmed by man7.org
How do I stop it coming back?
- Do not export TERMINFO in a profile unless the folder really holds a terminfo tree.
- When you build minimal images, include a terminfo database or copy the entries you need.
- Check infocmp on a new server before blaming the editor.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Servers
dnf cannot install MySQL on Amazon Linux 2023
dnf cannot find a mysql-server package on Amazon Linux 2023
Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.
3 causes, each with a fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
Apache warns that a ${VAR} config variable is not defined
${VAR} left unchanged in the configuration, with a warning in the error log
Apache expands ${VAR} from Define or from the shell environment that exists when the server starts.
3 causes, each with a fix