SSH-Fehler „unknown terminal type“ beheben
Die Meldung „unknown terminal type“ entsteht durch einen fehlenden TERM-Eintrag auf dem Server. Installieren Sie terminfo im Home-Verzeichnis, ganz ohne root.
Was „unknown terminal type“ bedeutet
Ein Fehler wegen eines unbekannten Terminaltyps über SSH bedeutet, dass der Name in TERM keinen passenden Eintrag in der terminfo-Datenbank auf dem Server hat. Ihr Emulator setzt diesen Namen auf Ihrem Laptop. Die Datenbank, die ihn erkennen muss, befindet sich auf dem entfernten Rechner. Wenn die Suche fehlschlägt, beendet sich jedes curses-Programm auf diesem Server, bevor es etwas ausgibt, weil ihm die Beschreibung der Fähigkeiten Ihres Terminals fehlt.
Die Lösung, bei der alle Funktionen Ihres Emulators erhalten bleiben, besteht aus einem Befehl: Kompilieren Sie Ihren eigenen terminfo-Eintrag auf dem Server in ~/.terminfo. Bei einem Standard-Build wie dem von Debian durchsucht ncurses zuerst Ihr Home-Verzeichnis und danach erst die Systemverzeichnisse. Nur eine gesetzte Variable $TERMINFO wird vorher geprüft. Dafür benötigen Sie weder root noch ändern Sie etwas für andere Benutzer. Die Suche im Home-Verzeichnis ist in ncurses optional. Deshalb ist die Prüfung nach der Behebung wichtig.
TERM ist ein Name, terminfo ist die Datenbank
TERM enthält eine Zeichenkette, und diese Zeichenkette ist nur ein Schlüssel. terminfo ist eine kompilierte Datenbank mit Terminalbeschreibungen. Über den Schlüssel findet ein Programm den passenden Eintrag. Eine Beschreibung enthält unter anderem die Anzahl der Terminalfarben, die Bytefolge für die Cursorposition in Zeile 12, Spalte 40, die Bytefolge, die die Taste F5 sendet, und die Information, ob das Terminal eine formatierte Unterstreichung darstellen kann. ncurses, die Bibliothek, auf der fast jede textbasierte Benutzeroberfläche unter Linux aufbaut, liest diese Beschreibung beim Start. Programme wie top, less, nano und watch können ohne sie keinen einzigen Bildschirm darstellen.
Sehen Sie sich Ihren eigenen Eintrag an:
echo "$TERM"
tput longname
infocmp -1 | head -20tput longname gibt die für Menschen lesbare Beschreibung des Eintrags aus, den TERM bezeichnet. Für xterm-256color lautet die Ausgabe:
xterm with 256 colorsinfocmp -1 dekompiliert den Eintrag und gibt eine Fähigkeit pro Zeile aus. Erweiterte, benutzerdefinierte Fähigkeiten werden nicht ausgegeben, sofern Sie nicht -x ergänzen, wie in infocmp -1 -x. Wenn beide Befehle funktionieren, kennt die Datenbank auf diesem Computer dieses Terminal. Diesen Zustand benötigen Sie auch auf der anderen Seite einer SSH-Verbindung.
Warum es nur über SSH fehlschlägt
SSH sendet den Namen und nichts weiter. Wenn der Client ein Pseudo-Terminal anfordert, wird TERM zusammen mit dieser Anfrage übertragen. Das OpenSSH-Handbuch ist eindeutig: „Die Umgebungsvariable TERM wird immer gesendet, wenn ein Pseudo-Terminal angefordert wird, da sie vom Protokoll benötigt wird.“ Ihre Login-Shell auf dem VPS erhält also TERM=xterm-ghostty, xterm-kitty oder den Namen, den Ihr Emulator verwendet. Die Beschreibung hinter diesem Namen bleibt auf Ihrem Laptop in dessen Datenbank. Ein Server, der vor der Entwicklung Ihres Emulators eingerichtet wurde, kennt diesen Namen nicht. Nichts in der SSH-Verbindung selbst kopiert Terminalbeschreibungen, und das ist beabsichtigt: Das Protokoll überträgt einen Namen, keine Auflistung der Fähigkeiten.
Reproduzieren Sie den Fehler auf Ihrem eigenen Rechner mit einem Namen, der garantiert nicht vorhanden ist:
TERM=xterm-nosuchthing tput colors
echo "$?"tput: unknown terminal "xterm-nosuchthing"Der Exit-Status ist 3. Das tput-Handbuch dokumentiert ihn als „nicht erkannten Terminaltyp“. Jedes curses-Programm führt dieselbe Suche durch. Ein fehlender Name erzeugt daher in jedem Programm eine andere Meldung, obwohl allen derselbe Fehler zugrunde liegt. nano wird mit Error opening terminal: xterm-nosuchthing. beendet. Das ist der standardmäßige ncurses-Fehler, wenn beim Start keine Beschreibung geladen werden kann. vim gibt E558: Terminal entry not found in terminfo aus. less gibt WARNING: terminal is not fully functional aus. Ein Pager, der nur teilweise funktioniert, und ein Editor, der den Start verweigert, wirken wie voneinander unabhängige Fehler. Tatsächlich fehlt in beiden Fällen dieselbe Datei.
Wo ncurses nach dem Eintrag sucht
ncurses durchsucht die Verzeichnisse in einer festen Reihenfolge, die in terminfo(5) dokumentiert ist:
$TERMINFO, sofern es gesetzt ist. Dieses Verzeichnis wird zuerst geprüft.$HOME/.terminfo. Das Handbuch bezeichnet dies als „optionale Funktion, die vollständig aus der Bibliothek entfernt werden kann“, oder als Funktion, die so eingeschränkt werden kann, dass privilegierte Programme sie nicht versehentlich verwenden.- Alle in
$TERMINFO_DIRSaufgeführten Verzeichnisse. - Die beim Kompilieren festgelegten Verzeichnisse. Unter Debian und Ubuntu gehören dazu
/etc/terminfo,/lib/terminfound/usr/share/terminfo.
Führen Sie auf dem Server infocmp -D aus, um die Liste auszugeben, die der dort installierte ncurses-Build tatsächlich verwendet. Verlassen Sie sich nicht auf die oben genannten Pfade. Schritt 2 ist der entscheidende Punkt. Der ncurses-Build von Debian deaktiviert diese Funktion nicht. Wenn sie vorhanden ist, wird Ihr Home-Verzeichnis vor jedem Systemverzeichnis durchsucht. Eine Datei unter ~/.terminfo behebt die Suche daher für Ihr Konto, ohne dass Sie ein Paket installieren oder root benötigen. Führen Sie nach der Korrektur tput longname aus. Damit prüfen Sie, ob der Build auf Ihrem Server diese Funktion berücksichtigt. Die einzige Ausnahme ist Schritt 1: Wenn echo "$TERMINFO" auf dem Server eine Ausgabe erzeugt, wird dieser Pfad zuerst geprüft. Ein Eintrag mit demselben Namen hat dort Vorrang vor Ihrem Eintrag.
Fix 1: Verwenden Sie einen TERM-Wert, den der Server bereits kennt
Am schnellsten können Sie die Blockade umgehen, indem Sie für eine Verbindung ein anderes Terminal angeben:
TERM=xterm-256color ssh user@203.0.113.10Tragen Sie dies für den Host dauerhaft in ~/.ssh/config auf Ihrem Laptop ein:
Host vps1
HostName 203.0.113.10
User deploy
SetEnv TERM=xterm-256colorDie Verwendung von SetEnv zum Überschreiben von TERM erfordert auf dem Client OpenSSH 8.7 oder neuer. Diese Version wurde im August 2021 veröffentlicht. Ältere Clients senden unabhängig von dieser Zeile weiterhin den eigenen TERM-Wert des Terminalemulators. TERM ist die einzige Variable, für die keine Zustimmung des Servers erforderlich ist: Im Handbuch heißt es: „Wie bei SendEnv muss der Server vorbereitet sein, die Umgebungsvariable zu akzeptieren; davon ausgenommen ist die Variable TERM.“ Daher funktioniert dies auch mit einem gehärteten sshd, in dem überhaupt keine AcceptEnv-Zeile vorhanden ist.
Der Nachteil: Alles, was Ihr Terminalemulator über einfaches xterm-256color hinaus beschreibt, steht nicht mehr zur Verfügung. Dazu gehören 24-Bit-Farben, die über die Fähigkeit RGB angekündigt werden, sowie formatierte Unterstreichungen über Smulx. Programme, die auf den terminfo-Eintrag angewiesen sind, können diese Fähigkeiten nicht mehr erkennen. Sie verwenden daher 256 Farben und einfache Unterstreichungen, sofern Sie sie nicht so konfigurieren, dass sie die Sequenzen trotzdem senden. Vim kann beispielsweise mit set termguicolors weiterhin 24-Bit-Farben darstellen, weil die integrierten Sequenzen t_8f und t_8b mit den meisten Terminals funktionieren. Die Anzeige funktioniert. Sie ist lediglich weniger leistungsfähig als das von Ihnen ausgewählte Terminal.
Beheben Sie das Problem nicht, indem Sie export TERM=xterm-256color zu .bashrc auf dem Server hinzufügen. Diese Datei wird für jede Verbindung ausgeführt, auch für Verbindungen von einem Terminal, dessen Name dem Server bekannt ist. Dadurch werden Sitzungen herabgestuft, die bereits korrekt funktioniert haben. Lassen Sie die Überschreibung auf dem Client, wo Sie wissen, welchen Terminalemulator Sie verwenden.
Fix 2: Ihren terminfo-Eintrag einmalig an den Server übertragen
Diese Lösung erhält Ihren Emulator unverändert. Dekompilieren Sie den Eintrag lokal, übertragen Sie ihn über SSH und kompilieren Sie ihn auf dem Zielsystem:
infocmp -x | ssh user@203.0.113.10 -- tic -x -infocmp -x gibt den Eintrag für Ihren aktuellen TERM als Quelltext aus, einschließlich erweiterter (benutzerdefinierter) Fähigkeiten. tic -x kompiliert diesen Quelltext auf dem Server wieder zu einer binären Beschreibung. Das -x auf beiden Seiten ist wichtig. Ohne diese Option gehen Fähigkeiten wie Smulx bei der Übertragung verloren, und Sie übertragen eine eingeschränkte Kopie Ihres eigenen Terminals.
tic schreibt, sofern möglich, in das Systemverzeichnis. Wenn der Benutzer dort keine Schreibrechte hat, wird auf $HOME/.terminfo zurückgegriffen. Ein normales Konto auf einem VPS erhält das Home-Verzeichnis. Das ist in diesem Fall gewünscht. Sie können das Ziel auch angeben:
infocmp -x | ssh user@203.0.113.10 -- tic -x -o '~/.terminfo' /dev/stdinDie Anführungszeichen um ~/.terminfo sind erforderlich. ssh fügt die Befehlswörter zu einer Zeichenkette zusammen und übergibt sie an die Remote-Shell. Ohne Anführungszeichen wird ~ zuerst von Ihrer lokalen Shell expandiert. Sie übertragen dann ein wörtliches /home/yourname/.terminfo an einen Rechner, auf dem Ihr Konto möglicherweise anders heißt. tic schlägt mit einem Berechtigungsfehler fehl oder schreibt in einen Pfad, den ncurses nicht durchsucht. Setzen Sie die Tilde in Anführungszeichen, damit die Remote-Shell sie expandiert.
Melden Sie sich an und prüfen Sie den Eintrag:
ssh user@203.0.113.10
tput longname
ls -R ~/.terminfotput longname gibt die Beschreibung Ihres Terminals aus. Das bedeutet, dass die Suche jetzt erfolgreich ist. ls zeigt die kompilierte Datei in einem Unterverzeichnis an, das nach dem ersten Buchstaben des Terminalnamens benannt ist. Führen Sie anschließend top aus oder überwachen Sie mit watch -n1 uptime die Ausgabe, die über dieselbe Bibliothek neu gezeichnet wird, um zu bestätigen, dass ein echtes curses-Programm den Bildschirm korrekt darstellt.
Der Aufwand: ein Schritt pro Server. Der Eintrag liegt im Home-Verzeichnis eines Kontos auf einem Rechner. Wenn Sie den VPS neu erstellen, ist der Eintrag verloren. Nehmen Sie den Befehl in das Verfahren auf, das Sie zum Bereitstellen und Verwalten mehrerer Server gleichzeitig verwenden. Dann wird der Eintrag auf einem neuen Host bereits kompiliert eingerichtet.
Fix 3: Die erweiterte terminfo-Datenbank installieren
Wenn Sie root-Rechte haben und der Name für jedes Konto auf dem System aufgelöst werden soll:
sudo apt update
sudo apt install ncurses-term
tput -T xterm-ghostty longnamencurses-term enthält die Terminalbeschreibungen, die bei der Basisinstallation fehlen. Damit wird der Name für root und für alle anderen Benutzer aufgelöst. Das ist bei Fix 2 nicht der Fall.
Das hilft nur, wenn der Eintrag für Ihr Terminal in der ncurses-Version vorhanden ist, die Ihre Distribution paketiert hat. Prüfen Sie das daher, statt es vorauszusetzen. Ubuntu 24.04 liefert ncurses-bin 6.4+20240113-1ubuntu2.2 (Stand: November 2026). Der Ghostty-Eintrag wurde im Upstream-Projekt in ncurses 6.5-20241228 hinzugefügt. Diese Version ist neuer. Daher kann apt install ncurses-term unter Ubuntu 24.04 unabhängig davon, wie oft Sie es ausführen, keinen xterm-ghostty-Eintrag erzeugen. tput -T <name> longname ist die Prüfung: Der Befehl gibt die Beschreibung aus, wenn der Eintrag vorhanden ist, und unknown terminal mit Exit-Status 3, wenn er fehlt.
Um statt des gesamten Pakets nur einen einzelnen Eintrag systemweit zu installieren, kopieren Sie die Quelldatei und kompilieren Sie sie als 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.srcDas -t im zweiten Befehl weist ein Pseudo-Terminal zu, damit sudo zur Eingabe des Passworts auffordern kann. Ohne diese Option weist ssh einem Remote-Befehl kein Terminal zu. Wenn ein Passwort erforderlich ist, beendet sich sudo dann mit sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper. Dieser Fehler betrifft das fehlende tty, nicht terminfo.
Emulator die Übertragung ausführen lassen
Einige Emulatoren enthalten einen Helfer, der Fix 2 für Sie übernimmt. kitty verfügt über ein ssh-Kitten: kitten ssh myserver stellt die Verbindung her und kopiert kittys terminfo automatisch auf den Remote-Host. Die Dokumentation beschreibt außerdem die manuelle Form infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, bei der die Tilde aus dem oben beschriebenen Grund maskiert wird. Ghostty dokumentiert infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - und unterstützt seit Version 1.2.0 optionale Funktionen zur Shell-Integration (ssh-env und ssh-terminfo), die beide Fixes automatisieren. Ghostty 1.4.0, veröffentlicht am 27. Oktober 2026, ergänzt einen ghostty +ssh-Wrapper, den die Versionen 1.3.x nicht enthalten. Die beiden optionalen Funktionen verwenden nun diesen Wrapper. Er installiert die mit Ghostty gebündelte terminfo auf dem Remote-Host, bevor die Verbindung hergestellt wird, und verwendet TERM=xterm-256color, wenn die Installation fehlschlägt, beispielsweise weil auf dem Server kein tic vorhanden ist. In 1.4 überschreibt ssh-env außerdem keine SetEnv-Zeilen in ~/.ssh/config mehr. Dadurch wird eine hostspezifische Überschreibung aus Fix 1 berücksichtigt.
Diese Helfer führen dieselben Befehle aus, die Sie gerade manuell ausgeführt haben. Die manuelle Form bleibt trotzdem wichtig, weil der Helfer nicht eingreifen kann, wenn die Verbindung an einer anderen Stelle beginnt, auf einem Jump-Host oder innerhalb eines Skripts.
Wenn der Fehler wieder auftritt
Unter sudo -i. Eine Login-Shell als root hat HOME=/root, und sudo behält Ihr TERM bei. ncurses sucht nun in /root/.terminfo, das Ihren Eintrag nicht enthält. Daher tritt der Fehler nur für root erneut auf. Bestätigen Sie dies mit sudo -i env und lesen Sie die Zeilen HOME und TERM. Installieren Sie den Eintrag im Systemverzeichnis. Eine Kopie in /root/.terminfo kann ebenfalls funktionieren. ncurses kann die Suche im Home-Verzeichnis für privilegierte Prozesse jedoch einschränken. Führen Sie daher tput longname als root aus, um dies zu bestätigen.
Innerhalb von tmux oder screen. Diese Programme setzen für die darin ausgeführten Programme ein eigenes TERM, üblicherweise screen-256color oder tmux-256color. Ein älterer Server kennt screen-256color möglicherweise, aber nicht tmux-256color. Dadurch funktioniert die äußere Shell, während innerhalb der Sitzung alles fehlschlägt. Die Ursache ist dieselbe, nur der Name ist anders. Führen Sie auf dem Server tput -T tmux-256color longname aus, um zu sehen, welchen der beiden Einträge er kennt. Eine auf tmux basierende Terminal-Arbeitsumgebung kann dies verbergen, bis Sie sich an einem Host anmelden, den Sie noch nicht repariert haben.
Auf einem neuen Server. ~/.terminfo gilt pro Konto und pro Rechner. Ein neu erstellter VPS ist daher wieder leer.
Die Anzeige funktioniert, aber Tasten verhalten sich falsch. Wenn die Anzeige korrekt ist, aber Home, End oder die Funktionstasten unerwartete Zeichen einfügen, wurde der Name zu einem Eintrag aufgelöst, der nicht zu Ihrem Terminal passt. Die Tastensequenzen stammen aus demselben terminfo-Eintrag wie die Funktionen für die Darstellung. Ein angenäherter Eintrag liefert daher auch nur angenäherte Tastensequenzen. Das ist normalerweise das Ergebnis von Korrektur 1 bei einem Emulator, dessen Tastensequenzen sich von xterm unterscheiden. Korrektur 2 ist die sauberste Lösung, weil der tatsächliche Eintrag Ihres Emulators für jedes Programm gleichzeitig die richtigen Sequenzen bereitstellt. Dies ist jedoch nicht der einzige Weg: Die Dokumentation von Vim sagt, dass Sie „den Tastencode mit dem Befehl :set ändern“ können. Vim fragt beim Start außerdem einen aktuellen xterm direkt nach dessen Tastencodes, statt sich ausschließlich auf den Eintrag zu verlassen.
FAQ
Warum sehe ich über SSH nur „unknown terminal type“?
Weil sich die Datenbank mit dem Eintrag Ihres Terminals auf dem Server befindet. Ihr Emulator installiert seine Beschreibung auf dem Rechner, auf dem er ausgeführt wird. Lokale Programme finden sie daher ohne weiteres Zutun. SSH überträgt nur den Wert von TERM, weil das Protokoll diesen Namen mit der Anforderung für das Pseudo-Terminal übermittelt. Das entfernte ncurses sucht den Namen in der entfernten Datenbank und findet keinen Eintrag. Daher schlägt initscr fehl und das Programm wird beendet.
Kann ich das ohne root-Rechte auf dem Server beheben?
Ja, bei einer Standardinstallation wie der von Debian. ncurses durchsucht $HOME/.terminfo vor allen Systemverzeichnissen. Nur eine auf dem Server gesetzte Variable $TERMINFO wird noch früher geprüft. Im Normalfall reicht daher ein Eintrag an dieser Stelle für Ihr Konto aus. Die Suche im Home-Verzeichnis ist in ncurses optional. Deshalb ist die nachfolgende Prüfung von tput longname wichtig. Führen Sie infocmp -x | ssh user@host -- tic -x - einmal pro Server aus. tic schreibt in Ihr Home-Verzeichnis, wenn der Systempfad nicht beschreibbar ist. Für ein Konto ohne privilegierte Rechte ist das der Normalfall. Melden Sie sich an und führen Sie tput longname aus, um zu bestätigen, dass der Eintrag jetzt gefunden wird.
Was verliere ich, wenn ich TERM=xterm-256color für einen Host festlege?
Alle Funktionen, die Ihr Emulator zusätzlich zum Eintrag xterm-256color beschreibt, beispielsweise 24-Bit-Farben über RGB und formatierte Unterstreichungen über Smulx. Programme, die sich auf den terminfo-Eintrag stützen, können diese Funktionen nicht erkennen. Sie verwenden daher den nächstliegenden Fallback, sofern Sie dies nicht anders konfigurieren, wie es Vim mit der Option termguicolors für Farben macht. Auch die Sequenzen für Funktionstasten können von denen Ihres tatsächlichen Terminals abweichen. Legen Sie die Einstellung auf dem Client in ~/.ssh/config fest und nicht in einer .bashrc auf dem Server. Andernfalls würden Sitzungen von Terminals, die bereits funktionieren, herabgestuft.
Warum tritt der Fehler nach sudo -i wieder auf?
sudo -i startet mit HOME=/root eine Login-Shell als root und behält dabei den Wert von TERM bei. ncurses durchsucht anschließend /root/.terminfo statt Ihres eigenen Home-Verzeichnisses und findet dort keinen Eintrag. root sieht daher denselben Fehler, der bei Ihrem Konto nicht mehr auftritt. Führen Sie sudo -i env aus und prüfen Sie die Zeilen HOME und TERM. Kompilieren Sie den Eintrag mit sudo tic -x -o /usr/share/terminfo in das Systemverzeichnis. Eine Kopie in /root/.terminfo kann ebenfalls funktionieren. ncurses kann die Suche im Home-Verzeichnis für privilegierte Prozesse jedoch einschränken. Bestätigen Sie dies daher mit tput longname als root.
Behebt apt install ncurses-term das Problem immer?
Nein. Der Befehl fügt nur die Einträge hinzu, die in der von Ihrer Distribution paketierten ncurses-Version vorhanden waren. Ubuntu 24.04 wird mit ncurses 6.4 ausgeliefert (ncurses-bin 6.4+20240113-1ubuntu2.2, Stand November 2026). Der Eintrag für Ghostty wurde jedoch erst in ncurses 6.5-20241228 upstream hinzugefügt. Dieses Paket kann ihn daher nicht enthalten. Prüfen Sie dies mit tput -T <name> longname, bevor Sie sich auf das Paket verlassen. Wenn die Prüfung weiterhin ein unbekanntes Terminal meldet, stellen Sie den Eintrag selbst bereit.