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

Qué significa «tipo de terminal desconocido»

El error de tipo de terminal desconocido mediante 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 portátil. La base de datos que debe reconocerlo se encuentra en la máquina remota. Si la búsqueda falla, todos los programas curses de ese servidor se detienen antes de mostrar 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 de inicio del usuario y después en los directorios del sistema. 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 es sólo una clave. terminfo es una base de datos compilada de descripciones de terminales, y la clave permite que un programa encuentre la descripción correcta. 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 prácticamente toda interfaz de texto de usuario en 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 indique TERM. Para xterm-256color muestra:

xterm with 256 colors

infocmp -1 descompila la entrada completa y muestra una capacidad por línea. Si ambos comandos funcionan, la base de datos de este equipo conoce este terminal. Ese es también el estado que necesita en el otro extremo 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 realiza la búsqueda en un orden fijo, documentado en terminfo(5):

1. $TERMINFO, si está definido. Sólo se busca en ese directorio.
2. $HOME/.terminfo.
3. Todos los directorios incluidos en $TERMINFO_DIRS.
4. Las ubicaciones integradas durante la compilación, 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 archivo en ~/.terminfo corrige la búsqueda para su cuenta sin instalar paquetes ni usar root.

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 conexión:

TERM=xterm-256color ssh user@203.0.113.10

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

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

SetEnv requiere OpenSSH 7.8 o posterior en el cliente, versión publicada en agosto de 2018. TERM es la única variable que no necesita autorización del servidor: el manual indica lo siguiente: «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, funciona incluso contra un sshd reforzado que no tenga 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 ya no pueden detectar esas capacidades, por lo que usan 256 colores y un subrayado normal. La pantalla funciona. Simplemente tiene menos capacidades que el terminal que ha elegido.

No intente resolverlo añadiendo export TERM=xterm-256color a su .bashrc en el servidor. Ese archivo se ejecuta para todas las conexiones, incluidas las procedentes de un terminal cuyo nombre sí conozca el servidor, por lo que degrada sesiones que ya funcionaban correctamente. Mantenga la sustitución en el cliente, donde sabe qué emulador está utilizando.

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.

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

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

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 los demás usuarios, algo que la corrección 2 no hace.

Sólo funciona si la entrada de su terminal existe en la versión de ncurses que empaquetó su distribución. Compruébelo en lugar de darlo por supuesto. Ubuntu 24.04 incluye ncurses-bin 6.4+20240113-1ubuntu2.1 (a fecha de agosto de 2026). La entrada de Ghostty se añadió en la versión ascendente ncurses 6.5-20241228, que es más reciente. Por tanto, 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 permite comprobarlo: 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 terminal pseudo, de modo que sudo puede solicitar la contraseña. Sin él, sudo puede terminar con sudo: no tty present and no askpass program specified.

Deje que el emulador realice la transferencia

Algunos emuladores incluyen un asistente que aplica la corrección 2 por usted. 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 - e incluye integración con el shell (ssh-env y ssh-terminfo), además de una acción +ssh que automatiza ambas correcciones.

Estos asistentes ejecutan los mismos comandos que acaba de ejecutar manualmente. Aun así, es importante conocer la forma manual, porque el asistente no puede actuar cuando la conexión se inicia desde 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 ninguna intervención. 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, por lo que 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 habitual con una cuenta sin privilegios. Inicie sesión y ejecute tput longname para confirmar que la búsqueda ya se resuelve.

¿Qué pierdo al configurar 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 no pueden ver esas capacidades, por lo que usan la alternativa más cercana. Las secuencias de las teclas de función también pueden diferir de las de su terminal real. Coloque la configuración 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. Entonces ncurses busca /root/.terminfo en lugar del directorio personal del usuario y no encuentra nada, por lo que root ve el mismo fallo que ya no ve su cuenta. 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.1, a fecha de agosto de 2026), y la entrada de Ghostty se añadió en ncurses 6.5-20241228, por lo que ese paquete no puede contenerla. Compruébelo con tput -T <name> longname antes de confiar en el paquete y proporcione usted mismo la entrada si la comprobación sigue indicando que el terminal es desconocido.