Cómo corregir «tipo de terminal desconocido» en SSH

Qué significa "unknown terminal type"

Un error de tipo de terminal desconocido por SSH significa que el nombre de TERM no tiene ninguna entrada coincidente en la base de datos terminfo del servidor. El emulador establece ese nombre en su equipo. La base de datos que debe reconocerlo se encuentra en la máquina remota. Cuando falla la búsqueda, todos los programas curses de ese servidor se detienen antes de dibujar nada porque no tienen una descripción de las capacidades de su terminal.

La solución que conserva todas las funciones del emulador consiste en compilar una entrada terminfo propia en ~/.terminfo del servidor. ncurses busca primero en el directorio personal, antes que en cualquier directorio del sistema (sólo se comprueba antes una variable $TERMINFO, si está definida). Por tanto, no necesita root ni modifica nada para los demás usuarios.

TERM es un nombre; terminfo es la base de datos

TERM contiene una cadena, y esa cadena sólo es una clave. terminfo es una base de datos compilada de descripciones de terminales, y la clave indica a un programa cuál debe usar. Una descripción registra cuántos colores tiene el terminal, qué bytes mueven el cursor a la fila 12, columna 40, qué bytes envía la tecla F5 y si puede dibujar un subrayado con estilo. ncurses, la biblioteca en la que se basa casi toda interfaz de texto de Linux, lee esa descripción al iniciarse. Programas como top, less, nano y watch no pueden mostrar una sola pantalla sin ella.

Consulte su propia entrada:

echo "$TERM"
tput longname
infocmp -1 | head -20

tput longname muestra la descripción legible del nombre que indica TERM. Para xterm-256color, muestra:

xterm with 256 colors

infocmp -1 descompila la entrada y muestra una capacidad por línea. Omite las capacidades extendidas, definidas por el usuario, a menos que añada -x, como en infocmp -1 -x. Si ambos comandos funcionan, la base de datos de este equipo conoce este terminal. Ese es también el estado que necesita en el extremo remoto de una conexión SSH.

Por qué sólo falla mediante SSH

SSH envía el nombre y nada más. Cuando el cliente solicita un terminal pseudo, TERM viaja con esa solicitud. El manual de OpenSSH lo deja claro: «la variable de entorno TERM siempre se envía cuando se solicita un terminal pseudo, porque el protocolo la necesita». Por tanto, el shell de inicio de sesión en el VPS recibe TERM=xterm-ghostty, xterm-kitty o el nombre que use el emulador. La descripción asociada a ese nombre permanece en el portátil, dentro de su base de datos. Un servidor creado antes de que existiera el emulador nunca ha conocido ese nombre. Nada en la propia conexión SSH copia las descripciones de terminal, y es intencionado: el protocolo transporta un nombre, no un volcado de capacidades.

Reproduzca el fallo en su propia máquina con un nombre que no exista:

TERM=xterm-nosuchthing tput colors
echo "$?"

tput: unknown terminal "xterm-nosuchthing"

El estado de salida es 3, que ncurses documenta como un tipo de terminal desconocido o una base de datos ausente. Todos los programas curses realizan la misma búsqueda, por lo que un solo nombre ausente produce un mensaje distinto en cada programa, aunque la causa sea la misma. nano se detiene con Error opening terminal: xterm-nosuchthing., el fallo estándar de ncurses cuando no puede cargar una descripción al iniciar. vim muestra E558: Terminal entry not found in terminfo. less muestra WARNING: terminal is not fully functional. Un paginador que funciona parcialmente y un editor que se niega a iniciar parecen errores sin relación. En realidad, les falta el mismo archivo.

Dónde busca ncurses la entrada

ncurses busca en un orden fijo, documentado en terminfo(5):

1. $TERMINFO, si está definida. Se comprueba primero.
2. $HOME/.terminfo.
3. Todos los directorios indicados en $TERMINFO_DIRS.
4. Las ubicaciones compiladas en ncurses, que en Debian y Ubuntu incluyen /etc/terminfo, /lib/terminfo y /usr/share/terminfo.

Ejecute infocmp -D en el servidor para mostrar la lista que utiliza su propia compilación de ncurses, en lugar de confiar en las rutas anteriores. El paso 2 es la clave. Su directorio personal se busca antes que cualquier directorio del sistema, por lo que un solo archivo en ~/.terminfo corrige la búsqueda para su cuenta sin instalar paquetes ni usar root. La única excepción es el paso 1: si echo "$TERMINFO" muestra algo en el servidor, esa ubicación se comprueba primero, y una entrada con el mismo nombre allí tiene prioridad sobre la suya.

Solución 1: use un TERM que el servidor ya conozca

La forma más rápida de desbloquear la conexión es indicar otro terminal para una sesión:

TERM=xterm-256color ssh user@203.0.113.10

Para dejarlo permanente para ese host, añádalo a ~/.ssh/config en su portátil:

Host vps1
    HostName 203.0.113.10
    User deploy
    SetEnv TERM=xterm-256color

Usar SetEnv para sobrescribir TERM requiere OpenSSH 8.7 o una versión posterior en el cliente, publicada en agosto de 2021. Los clientes más antiguos envían su propio TERM, independientemente de esta línea. TERM es la única variable que no requiere autorización del servidor: el manual indica que «al igual que con SendEnv, salvo en el caso de la variable TERM, el servidor debe estar preparado para aceptar la variable de entorno». Por tanto, esto funciona incluso contra un sshd reforzado sin ninguna línea AcceptEnv.

El coste es perder todo lo que su emulador describa más allá de xterm-256color básico. Esto incluye el color de 24 bits anunciado mediante la capacidad RGB y los subrayados con estilo mediante Smulx. Los programas que dependen de la entrada de terminfo ya no pueden ver esas capacidades, por lo que recurren a 256 colores y a un subrayado normal, a menos que los configure para enviar igualmente esas secuencias. Por ejemplo, Vim todavía puede mostrar color de 24 bits con set termguicolors, porque sus secuencias t_8f y t_8b integradas funcionan con la mayoría de los terminales. La pantalla funciona. Simplemente tiene menos capacidades que el terminal que eligió.

No solucione esto añadiendo export TERM=xterm-256color a su .bashrc en el servidor. Ese archivo se ejecuta para todas las conexiones, incluidas las conexiones desde un terminal cuyo nombre sí conoce el servidor, por lo que degrada sesiones que ya funcionaban correctamente. Mantenga la sobrescritura en el cliente, donde sabe qué emulador está ejecutando.

Solución 2: envíe la entrada terminfo al servidor una sola vez

Esta solución mantiene intacto su emulador. Descompile la entrada localmente, pásela por SSH y compílela en el equipo remoto:

infocmp -x | ssh user@203.0.113.10 -- tic -x -

infocmp -x muestra la entrada correspondiente a su TERM actual como texto fuente, incluidas las capacidades extendidas (definidas por el usuario). tic -x vuelve a compilar ese texto fuente como una descripción binaria en el servidor. El -x en ambos extremos es importante, porque sin él se pierden durante la transferencia capacidades como Smulx y se envía una copia degradada de su propio terminal.

tic escribe en el directorio del sistema cuando puede y usa $HOME/.terminfo como alternativa cuando el usuario no tiene permisos de escritura allí. Una cuenta normal en un VPS tiene disponible el directorio de inicio, que es lo que necesita. También puede indicar el destino:

infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdin

Las comillas alrededor de ~/.terminfo no son decorativas. ssh une las palabras del comando en una sola cadena y se la entrega al shell remoto, por lo que un ~ sin comillas se expande primero en su shell local. Después envía un /home/yourname/.terminfo literal a una máquina donde su cuenta puede tener otro nombre. tic falla con un error de permisos o escribe en una ruta que ncurses nunca busca. Ponga la tilde entre comillas para que el shell remoto la expanda.

Inicie sesión y compruebe el resultado:

ssh user@203.0.113.10
tput longname
ls -R ~/.terminfo

tput longname al mostrar la descripción de su terminal indica que la búsqueda ya funciona, y ls muestra el archivo compilado dentro de un subdirectorio cuyo nombre corresponde a la primera letra del nombre del terminal. Después ejecute top, o watch -n1 uptime, que redibuja la pantalla mediante la misma biblioteca, para confirmar que un programa curses real muestra la pantalla correctamente.

El coste es el siguiente: debe realizar un paso por servidor y la entrada queda en el directorio de inicio de una cuenta en una sola máquina. Si reconstruye el VPS, se pierde. Añada el comando a la herramienta que use para aprovisionar y administrar varios servidores a la vez, de modo que cada host nuevo reciba la entrada ya compilada.

Solución 3: instalar la base de datos terminfo ampliada

Si tiene root y quiere que el nombre se resuelva para todas las cuentas del equipo:

sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longname

ncurses-term contiene las descripciones de terminal que la instalación base omite. Corrige el nombre para root y para cualquier otro usuario, algo que la solución 2 no hace.

Sólo sirve cuando la entrada de su terminal existe en la versión de ncurses empaquetada por su distribución, así que debe comprobarlo en lugar de darlo por hecho. Ubuntu 24.04 incluye ncurses-bin 6.4+20240113-1ubuntu2.2 (a fecha de octubre de 2026). La entrada de Ghostty se añadió en ncurses 6.5-20241228, que es más reciente, por lo que apt install ncurses-term en Ubuntu 24.04 no puede generar una entrada xterm-ghostty, independientemente de cuántas veces lo ejecute. tput -T <name> longname es la comprobación: muestra la descripción cuando la entrada existe y unknown terminal con código de salida 3 cuando no existe.

Para instalar una sola entrada en todo el sistema en lugar del paquete completo, copie el código fuente y compílelo como root:

infocmp -x | ssh user@203.0.113.10 -- 'cat > /tmp/term.src'
ssh -t user@203.0.113.10 -- sudo tic -x -o /usr/share/terminfo /tmp/term.src

El -t del segundo comando asigna un pseudo terminal para que sudo pueda solicitar la contraseña. Sin él, sudo puede terminar con sudo: no tty present and no askpass program specified.

Deja que el emulador haga la transferencia

Algunos emuladores incluyen un asistente que aplica la corrección 2 automáticamente. kitty tiene un ssh kitten: kitten ssh myserver se conecta y copia automáticamente el terminfo de kitty al host remoto. Su documentación también muestra la forma manual, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, con la tilde escapada por el motivo descrito anteriormente. Ghostty documenta infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - y, desde la versión 1.2.0, incluye funciones opcionales de integración con el shell (ssh-env y ssh-terminfo) que automatizan ambas correcciones. Su documentación también describe un wrapper ghostty +ssh que, en octubre de 2026, sólo existe en compilaciones de desarrollo y no en las versiones 1.3.x.

Estos asistentes ejecutan los mismos comandos que acaba de ejecutar manualmente. Conocer la forma manual sigue siendo importante porque el asistente no puede actuar cuando la conexión se inicia en otro lugar, en un jump host o dentro de un script.

Cuando vuelve a aparecer el error

En sudo -i. Un shell de inicio de sesión como root tiene HOME=/root, y sudo conserva tu TERM. ncurses busca ahora en /root/.terminfo, que no contiene tu entrada, por lo que el fallo vuelve a producirse sólo para root. Confírmalo con sudo -i env y lee las líneas HOME y TERM. Instala la entrada en el directorio del sistema o coloca una copia en /root/.terminfo.

Dentro de tmux o screen. Estos programas establecen su propio TERM para los programas que se ejecutan dentro de ellos, normalmente screen-256color o tmux-256color. Un servidor antiguo conoce screen-256color y puede no conocer tmux-256color, por lo que el shell exterior funciona mientras todo lo que está dentro de la sesión falla. La causa es la misma, pero el nombre es diferente. Ejecuta tput -T tmux-256color longname en el servidor para ver cuál de los dos tiene. Un entorno de trabajo de terminal basado en tmux oculta este problema hasta que te conectas a un host que todavía no has corregido.

En un servidor nuevo. ~/.terminfo es específico de cada cuenta y cada máquina, por lo que una VPS reconstruida vuelve a quedar vacía.

La pantalla se muestra, pero las teclas funcionan mal. Si la pantalla se muestra correctamente, pero Home, End o las teclas de función insertan caracteres inesperados, el nombre se resolvió en una entrada que no coincide con tu terminal. Las secuencias de teclas proceden de la misma entrada de terminfo que las capacidades de representación, por lo que una entrada aproximada produce teclas aproximadas. Este es el resultado habitual de aplicar la corrección 1 en un emulador cuyas secuencias de teclas difieren de xterm. La corrección 2 resuelve el problema, porque sólo la entrada real de tu emulador contiene las secuencias correctas.

FAQ

¿Por qué sólo veo «unknown terminal type» mediante SSH?

Porque la base de datos que debe contener la entrada de su terminal es la del servidor. El emulador instala su descripción en el equipo donde se ejecuta, por lo que los programas locales la encuentran sin que tenga que hacer nada. SSH sólo envía el valor de TERM, porque el protocolo transmite ese nombre con la solicitud de pseudo-terminal. ncurses en el equipo remoto busca el nombre en la base de datos remota y no encuentra nada, por lo que initscr falla y el programa se detiene.

¿Puedo solucionarlo sin tener root en el servidor?

Sí. ncurses busca $HOME/.terminfo antes que cualquier directorio del sistema, y sólo una variable $TERMINFO definida en el servidor se comprueba antes, por lo que, en el caso normal, basta con colocar allí una entrada para su cuenta. Ejecute infocmp -x | ssh user@host -- tic -x - una vez por servidor. tic escribe en su directorio personal cuando no puede escribir en la ruta del sistema, que es lo normal para una cuenta sin privilegios. Inicie sesión y ejecute tput longname para confirmar que la búsqueda ya se resuelve.

¿Qué pierdo al establecer TERM=xterm-256color para un host?

Todas las capacidades que describe su emulador además de la entrada xterm-256color, como el color de 24 bits mediante RGB y los subrayados con estilo mediante Smulx. Los programas que dependen de la entrada terminfo no pueden ver esas capacidades, por lo que usan la alternativa más cercana, salvo que los configure de otra forma, como hace la opción termguicolors de Vim para el color. Las secuencias de las teclas de función también pueden diferir de las de su terminal real. Coloque el ajuste en el cliente, en ~/.ssh/config, y no en un .bashrc del servidor, ya que eso degradaría las sesiones de terminales que ya funcionaban.

¿Por qué vuelve a aparecer el error después de sudo -i?

sudo -i inicia un shell de inicio de sesión como root con HOME=/root, pero conserva el valor de TERM. ncurses busca entonces en /root/.terminfo en lugar de hacerlo en su propio directorio personal y no encuentra nada, por lo que root ve el mismo fallo que su cuenta ya no presenta. Ejecute sudo -i env y compruebe las líneas HOME y TERM. Compile la entrada en el directorio del sistema con sudo tic -x -o /usr/share/terminfo, o cópiela en /root/.terminfo.

¿apt install ncurses-term siempre lo soluciona?

No. Sólo añade las entradas que existían en la versión de ncurses incluida en el paquete de su distribución. Ubuntu 24.04 incluye ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, a fecha de octubre de 2026), y la entrada de Ghostty se añadió en sentido ascendente en ncurses 6.5-20241228, por lo que ese paquete no puede contenerla. Compruébelo con tput -T <name> longname antes de depender del paquete y proporcione la entrada manualmente si la comprobación sigue indicando un terminal desconocido.