Corriger « unknown terminal type » via SSH

Ce que signifie « unknown terminal type »

Une erreur de type de terminal inconnu via SSH signifie que le nom indiqué dans TERM ne correspond à aucune entrée de la base terminfo sur le serveur. Votre émulateur définit ce nom sur votre ordinateur portable. La base qui doit le reconnaître se trouve sur la machine distante. Lorsque la recherche échoue, tous les programmes curses de ce serveur s’arrêtent avant d’afficher quoi que ce soit, car ils ne disposent d’aucune description des fonctionnalités de votre terminal.

Pour conserver toutes les fonctionnalités de votre émulateur, il suffit d’exécuter une commande : compilez votre propre entrée terminfo dans ~/.terminfo sur le serveur. ncurses recherche d’abord dans votre répertoire personnel, avant les répertoires système. Cette méthode ne nécessite donc pas root et ne modifie rien pour les autres utilisateurs.

TERM est un nom, terminfo est la base de données

TERM contient une chaîne, et cette chaîne n’est qu’une clé. terminfo est une base de données compilée de descriptions de terminaux, et la clé permet à un programme de trouver la bonne description. Une description indique le nombre de couleurs du terminal, les octets qui déplacent le curseur à la ligne 12, colonne 40, les octets envoyés par la touche F5 et la prise en charge ou non du soulignement avec style. ncurses, la bibliothèque sur laquelle s’appuient presque toutes les interfaces utilisateur texte sous Linux, lit cette description au démarrage. Des programmes comme top, less, nano et watch ne peuvent pas afficher un seul écran sans elle.

Affichez votre propre entrée :

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

tput longname affiche la description lisible par l’utilisateur de ce que désigne TERM. Pour xterm-256color, il affiche :

xterm with 256 colors

infocmp -1 désassemble l’entrée complète et affiche une capacité par ligne. Si les deux commandes fonctionnent, la base de données de cette machine connaît ce terminal. C’est aussi l’état nécessaire à l’autre extrémité d’une connexion SSH.

Pourquoi cela échoue uniquement via SSH

SSH envoie le nom, et rien d’autre. Lorsque le client demande un pseudo-terminal, TERM est transmis avec cette demande. Le manuel OpenSSH est explicite : « la variable d’environnement TERM est toujours envoyée lorsqu’un pseudo-terminal est demandé, car elle est requise par le protocole ». Votre shell de connexion sur le VPS reçoit donc TERM=xterm-ghostty, ou xterm-kitty, ou le nom utilisé par votre émulateur. La description associée à ce nom reste sur votre ordinateur portable, dans sa base de données. Un serveur installé avant la création de votre émulateur n’a jamais rencontré ce nom. Rien dans la connexion SSH elle-même ne copie les descriptions de terminaux, et c’est volontaire : le protocole transporte un nom, pas une liste de capacités.

Reproduisez l’erreur sur votre propre machine avec un nom qui n’existe certainement pas :

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

tput: unknown terminal "xterm-nosuchthing"

Le code de sortie est 3. ncurses le documente comme un type de terminal inconnu ou une base de données manquante. Chaque programme curses effectue la même recherche. Un seul nom manquant produit donc un message différent dans chaque programme, avec une cause commune. nano s’arrête avec Error opening terminal: xterm-nosuchthing., l’échec standard de ncurses lorsqu’il ne peut pas charger une description au démarrage. vim affiche E558: Terminal entry not found in terminfo. less affiche WARNING: terminal is not fully functional. Un pager qui fonctionne partiellement et un éditeur qui refuse de démarrer peuvent sembler présenter des problèmes sans rapport. Ils utilisent le même fichier manquant.

Répertoire où ncurses recherche l’entrée

ncurses effectue ses recherches dans un ordre fixe, documenté dans terminfo(5) :

1. $TERMINFO, s’il est défini. Seul ce répertoire est recherché.
2. $HOME/.terminfo.
3. Chaque répertoire indiqué dans $TERMINFO_DIRS.
4. Les emplacements intégrés à la compilation, qui comprennent /etc/terminfo, /lib/terminfo et /usr/share/terminfo sur Debian et Ubuntu.

Exécutez infocmp -D sur le serveur pour afficher la liste utilisée par sa propre version de ncurses, plutôt que de vous fier aux chemins ci-dessus. L’étape 2 est l’élément essentiel. Votre répertoire personnel est recherché avant tout répertoire système. Un seul fichier sous ~/.terminfo suffit donc à corriger la recherche pour votre compte, sans installer de paquet et sans utiliser root.

Correctif 1 : utiliser un TERM déjà connu du serveur

Le moyen le plus rapide de débloquer la connexion consiste à indiquer un autre terminal pour une seule connexion :

TERM=xterm-256color ssh user@203.0.113.10

Pour rendre ce réglage permanent pour cet hôte, ajoutez-le dans ~/.ssh/config sur votre ordinateur portable :

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

SetEnv nécessite OpenSSH 7.8 ou une version ultérieure sur le client, publiée en août 2018. TERM est la seule variable qui ne nécessite pas l’autorisation du serveur : le manuel précise que, « comme pour SendEnv, à l’exception de la variable TERM, le serveur doit être configuré pour accepter la variable d’environnement ». Cette solution fonctionne donc même avec un sshd renforcé qui ne contient aucune directive AcceptEnv.

Contrepartie : tout ce que votre émulateur décrit au-delà de xterm-256color simple. Cela inclut les couleurs 24 bits annoncées par la capacité RGB et les soulignements stylés via Smulx. Les programmes ne peuvent plus détecter ces capacités et reviennent donc à 256 couleurs et à un soulignement simple. L’affichage fonctionne. Il est simplement moins complet que celui du terminal que vous utilisez.

Ne corrigez pas le problème en ajoutant export TERM=xterm-256color dans votre .bashrc sur le serveur. Ce fichier est exécuté pour chaque connexion, y compris celles provenant d’un terminal dont le nom est connu du serveur. Il dégrade donc les sessions qui fonctionnaient déjà correctement. Conservez la surcharge côté client, là où vous savez quel émulateur vous utilisez.

Correctif 2 : envoyer votre entrée terminfo au serveur une seule fois

C’est le correctif qui conserve votre émulateur intact. Décompilez l’entrée localement, transmettez-la via SSH, puis compilez-la sur le serveur distant :

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

infocmp -x affiche l’entrée correspondant à votre TERM actuel sous forme de texte source, y compris les capabilities étendues (définies par l’utilisateur). tic -x recompile cette source en description binaire sur le serveur. Le -x des deux côtés est important : sans lui, les capabilities telles que Smulx sont supprimées pendant le transfert et vous installez une copie dégradée de votre propre terminal.

tic écrit dans le répertoire système lorsque c’est possible, puis utilise $HOME/.terminfo si l’utilisateur n’a pas les droits d’écriture à cet emplacement. Un compte standard sur un VPS utilise son répertoire personnel, ce qui est le comportement recherché. Vous pouvez également indiquer la destination :

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

Les guillemets autour de ~/.terminfo ne sont pas décoratifs. ssh regroupe les mots de la commande en une seule chaîne et la transmet au shell distant. Sans guillemets, ~ est d’abord développé par votre shell local. Vous envoyez alors un /home/yourname/.terminfo littéral à une machine où votre compte peut porter un autre nom. tic échoue avec une erreur de permissions ou écrit dans un chemin que ncurses ne recherche jamais. Entourez le tilde de guillemets afin que le shell distant le développe.

Connectez-vous et vérifiez :

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

tput longname affiche la description de votre terminal, ce qui signifie que la recherche aboutit désormais. ls affiche le fichier compilé dans un sous-répertoire portant le nom de la première lettre du terminal. Exécutez ensuite top ou surveillez uptime avec watch -n1, qui réaffiche le résultat via la même bibliothèque, afin de vérifier qu’un véritable programme curses affiche correctement l’écran.

Le coût : une étape par serveur, et l’entrée reste dans le répertoire personnel d’un seul compte sur une seule machine. Si vous reconstruisez le VPS, elle disparaît. Ajoutez la commande à l’outil que vous utilisez pour provisionner et gérer plusieurs serveurs simultanément, afin qu’un nouvel hôte dispose déjà de l’entrée compilée.

Correctif 3 : installer la base terminfo étendue

Si vous disposez des privilèges root et voulez que le nom soit reconnu pour tous les comptes du serveur :

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

ncurses-term contient les descriptions de terminaux absentes de l’installation de base. Il corrige le problème pour root et pour tous les autres utilisateurs, contrairement au correctif 2.

Cela ne fonctionne que si l’entrée de votre terminal existe dans la version de ncurses fournie par votre distribution. Vérifiez donc sa présence au lieu de partir du principe qu’elle existe. Ubuntu 24.04 fournit ncurses-bin 6.4+20240113-1ubuntu2.1 (en août 2026). L’entrée de Ghostty a été ajoutée en amont dans ncurses 6.5-20241228, qui est plus récent. Par conséquent, apt install ncurses-term sur Ubuntu 24.04 ne peut pas générer d’entrée xterm-ghostty, quel que soit le nombre de fois où vous l’exécutez. tput -T <name> longname effectue la vérification : il affiche la description si l’entrée est présente, et unknown terminal avec le code de sortie 3 si elle ne l’est pas.

Pour installer une seule entrée à l’échelle du système au lieu du paquet complet, copiez la source, puis compilez-la en tant que 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

Le -t de la deuxième commande alloue un pseudo-terminal afin que sudo puisse demander le mot de passe. Sans cela, sudo peut se terminer avec sudo: no tty present and no askpass program specified.

Laissez l’émulateur effectuer le transfert

Certains émulateurs fournissent un outil qui applique automatiquement la correction 2. kitty dispose d’un ssh kitten : kitten ssh myserver se connecte et copie automatiquement le terminfo de kitty sur l’hôte distant. Sa documentation présente également la forme manuelle, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, avec le tilde échappé pour la raison décrite plus haut. Ghostty documente infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - et fournit une intégration au shell (ssh-env et ssh-terminfo), ainsi qu’une action +ssh qui automatise les deux corrections.

Ces outils exécutent les mêmes commandes que celles que vous venez de lancer manuellement. Il reste important de connaître la forme manuelle, car l’outil ne peut pas intervenir lorsque la connexion est établie ailleurs, depuis un jump host ou dans un script.

Quand l’erreur réapparaît

Sous sudo -i. Un login shell lancé en tant que root a HOME=/root, et sudo conserve votre TERM. ncurses recherche alors /root/.terminfo, qui ne contient pas votre entrée. L’échec ne concerne donc plus que root. Confirmez-le avec sudo -i env, puis lisez les lignes HOME et TERM. Installez l’entrée dans le répertoire système ou placez-en une copie dans /root/.terminfo.

Dans tmux ou screen. Ces outils définissent leur propre TERM pour les programmes qui s’exécutent à l’intérieur. Il s’agit généralement de screen-256color ou tmux-256color. Un serveur plus ancien connaît screen-256color, mais peut ne pas connaître tmux-256color. Le shell externe fonctionne alors correctement, tandis que tout échoue dans la session. La cause est la même, mais le nom diffère. Exécutez tput -T tmux-256color longname sur le serveur pour voir lequel des deux il possède. Un environnement de travail terminal basé sur tmux masque ce problème jusqu’au jour où vous vous connectez à un hôte qui n’a pas encore été corrigé.

Sur un serveur neuf. ~/.terminfo dépend du compte et de la machine. Un VPS reconstruit repart donc de zéro.

L’écran s’affiche, mais les touches se comportent mal. Si l’affichage est correct, mais que les touches Home, End ou les touches de fonction insèrent des caractères inattendus, le nom a été associé à une entrée qui ne correspond pas à votre terminal. Les séquences de touches proviennent de la même entrée terminfo que les capacités d’affichage. Une entrée approximative produit donc des séquences de touches approximatives. C’est le résultat habituel de la correction 1 avec un émulateur dont les séquences de touches diffèrent de xterm. La correction 2 est la bonne solution, car seule l’entrée réelle de votre émulateur contient les séquences appropriées.

FAQ

Pourquoi ne vois-je que « unknown terminal type » avec SSH ?

Parce que la base de données qui doit contenir l’entrée de votre terminal se trouve sur le serveur. Votre émulateur installe sa description sur la machine où il s’exécute, et les programmes locaux la trouvent donc sans intervention de votre part. SSH envoie uniquement la valeur de TERM, car le protocole transmet ce nom avec la demande de pseudo-terminal. ncurses sur la machine distante recherche ce nom dans la base de données distante, ne trouve rien, puis initscr échoue et le programme s’arrête.

Puis-je corriger ce problème sans accès root sur le serveur ?

Oui. ncurses recherche $HOME/.terminfo avant tout répertoire système. Une entrée à cet emplacement suffit donc pour votre compte. Exécutez infocmp -x | ssh user@host -- tic -x - une fois par serveur. tic écrit dans votre répertoire personnel lorsqu’il ne peut pas écrire dans le chemin système, ce qui est le cas normal pour un compte sans privilèges. Connectez-vous, puis exécutez tput longname pour vérifier que la recherche aboutit maintenant.

Que perds-je en définissant TERM=xterm-256color pour un hôte ?

Toutes les capacités décrites par votre émulateur au-delà de l’entrée xterm-256color, comme la couleur 24 bits via RGB et les soulignements stylés via Smulx. Les programmes ne peuvent pas voir ces capacités et utilisent donc le fallback le plus proche. Les séquences des touches de fonction peuvent également différer de celles de votre terminal réel. Placez ce paramètre côté client dans ~/.ssh/config plutôt que dans un .bashrc sur le serveur, car cela dégraderait les sessions provenant de terminaux qui fonctionnaient déjà.

Pourquoi l’erreur réapparaît-elle après sudo -i ?

sudo -i démarre un login shell en tant que root avec HOME=/root, tout en conservant votre valeur TERM. ncurses recherche alors /root/.terminfo au lieu de votre propre répertoire personnel et ne trouve rien. root rencontre donc la même erreur que votre compte ne rencontre plus. Exécutez sudo -i env et vérifiez les lignes HOME et TERM. Compilez l’entrée dans le répertoire système avec sudo tic -x -o /usr/share/terminfo, ou copiez-la dans /root/.terminfo.

apt install ncurses-term corrige-t-il toujours le problème ?

Non. Il ajoute uniquement les entrées présentes dans la version de ncurses fournie par votre distribution. Ubuntu 24.04 fournit ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, en août 2026), tandis que l’entrée de Ghostty a été ajoutée en amont dans ncurses 6.5-20241228. Ce paquet ne peut donc pas la contenir. Vérifiez avec tput -T <name> longname avant de compter sur le paquet. Si la vérification signale toujours un terminal inconnu, installez vous-même l’entrée.