SSH-Fehler „unknown terminal type“ beheben

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 Remote-System. Wenn die Suche fehlschlägt, beendet jedes curses-Programm auf diesem Server seine Ausführung, bevor es etwas darstellt, weil keine Beschreibung der Fähigkeiten Ihres Terminals vorhanden ist.

Die Lösung, bei der alle Funktionen Ihres Emulators erhalten bleiben, besteht aus einem Befehl: Kompilieren Sie Ihren eigenen terminfo-Eintrag nach ~/.terminfo auf dem Server. ncurses durchsucht Ihr Home-Verzeichnis vor allen Systemverzeichnissen. Dafür benötigen Sie daher keinen root-Zugriff, und für andere Benutzer ändert sich nichts.

TERM ist ein Name, terminfo ist die Datenbank

TERM enthält eine Zeichenkette. Diese Zeichenkette ist nur ein Schlüssel. terminfo ist eine kompilierte Datenbank mit Terminalbeschreibungen. Der Schlüssel dient Programmen dazu, den richtigen Eintrag zu finden. Eine Beschreibung enthält beispielsweise die Anzahl der Farben des Terminals, die Bytefolge, mit der der Cursor in Zeile 12, Spalte 40 bewegt wird, die von der Taste F5 gesendete Bytefolge und die Information, ob das Terminal eine formatierte Unterstreichung darstellen kann. ncurses, die Bibliothek, auf der nahezu jede textbasierte Benutzeroberfläche unter Linux aufbaut, liest diese Beschreibung beim Start. Programme wie top, less, nano und watch können ohne diese Beschreibung keinen einzigen Bildschirm darstellen.

Prüfen Sie Ihren eigenen Eintrag:

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

tput longname gibt die lesbare Beschreibung dessen aus, was TERM bezeichnet. Für xterm-256color lautet die Ausgabe:

xterm with 256 colors

infocmp -1 dekompiliert den vollständigen Eintrag und gibt eine Fähigkeit pro Zeile aus. Wenn beide Befehle funktionieren, kennt die Datenbank auf diesem Rechner dieses Terminal. Diesen Zustand benötigen Sie auch auf der anderen Seite einer SSH-Verbindung.

Warum der Fehler nur über SSH auftritt

SSH überträgt den Namen und nichts anderes. Wenn der Client ein Pseudo-Terminal anfordert, wird TERM mit dieser Anfrage übertragen. Das OpenSSH-Handbuch formuliert es eindeutig: „Die Umgebungsvariable TERM wird immer übertragen, 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 der dortigen Datenbank. Ein Server, der vor der Existenz Ihres Emulators erstellt wurde, kennt diesen Namen nicht. Nichts in der SSH-Verbindung selbst kopiert Terminalbeschreibungen. 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 existiert:

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

tput: unknown terminal "xterm-nosuchthing"

Der Exit-Status ist 3. ncurses dokumentiert diesen Status als unbekannten Terminaltyp oder als fehlende Datenbank. Jedes curses-Programm führt dieselbe Suche durch. Ein einziger fehlender Name erzeugt daher in jedem Programm eine andere Meldung, obwohl allen Meldungen dieselbe Ursache 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 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 Pfade in einer festen Reihenfolge, die in terminfo(5) dokumentiert ist:

1. $TERMINFO, sofern die Variable gesetzt ist. Es wird nur dieses Verzeichnis durchsucht.
2. $HOME/.terminfo.
3. Jedes in $TERMINFO_DIRS aufgeführte Verzeichnis.
4. Die einkompilierten Pfade. Unter Debian und Ubuntu gehören dazu /etc/terminfo, /lib/terminfo und /usr/share/terminfo.

Führen Sie auf dem Server infocmp -D aus, um die Pfadliste der dort verwendeten ncurses-Version auszugeben. Verlassen Sie sich nicht auf die oben genannten Pfade. Schritt 2 ist entscheidend. Ihr Home-Verzeichnis wird vor jedem Systemverzeichnis durchsucht. Daher behebt eine Datei unter ~/.terminfo das Lookup für Ihr Konto, ohne dass Sie ein Paket installieren oder root benötigen.

Fix 1: Einen Terminaltyp verwenden, den der Server bereits kennt

Die schnellste Lösung besteht darin, für eine Verbindung einen anderen Terminaltyp anzugeben:

TERM=xterm-256color ssh user@203.0.113.10

Machen Sie diese Einstellung auf Ihrem Laptop in ~/.ssh/config für diesen Host dauerhaft:

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

SetEnv erfordert auf dem Client OpenSSH 7.8 oder neuer. Diese Version wurde im August 2018 veröffentlicht. TERM ist die einzige Variable, für die keine Freigabe durch den Server erforderlich ist: Im Handbuch steht: „Ähnlich wie bei SendEnv muss der Server die Umgebungsvariable akzeptieren, mit Ausnahme der Variable TERM.“ Daher funktioniert dies auch mit einem gehärteten sshd, in dessen Konfiguration überhaupt keine AcceptEnv-Zeile vorhanden ist.

Der Nachteil: Alles, was Ihr Emulator zusätzlich zu einfachem xterm-256color beschreibt, geht verloren. Dazu gehören 24-Bit-Farben, die über die Fähigkeit RGB angekündigt werden, sowie formatierte Unterstreichungen über Smulx. Programme können diese Fähigkeiten nicht mehr erkennen und wechseln daher zu 256 Farben und einer einfachen Unterstreichung. Der Bildschirm funktioniert weiterhin. Er bietet lediglich weniger Funktionen als der ausgewählte Terminaltyp.

Lösen Sie das Problem nicht, indem Sie export TERM=xterm-256color zu Ihrer .bashrc auf dem Server hinzufügen. Diese Datei wird für jede Verbindung ausgeführt, auch für Verbindungen von einem Terminal, dessen Name der Server kennt. Dadurch werden Sitzungen herabgestuft, die bereits korrekt funktioniert haben. Belassen Sie die Überschreibung auf dem Client, wo Sie wissen, welchen Emulator 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/stdin

Die 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 ~/.terminfo

tput 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: 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 longname

ncurses-term enthält die Terminalbeschreibungen, die bei der Basisinstallation fehlen. Damit wird der Name für root und für alle anderen Benutzer verfügbar. 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 enthält ncurses-bin 6.4+20240113-1ubuntu2.1 (Stand August 2026). Der Ghostty-Eintrag wurde upstream in ncurses 6.5-20241228 hinzugefügt. Diese Version ist neuer. Daher kann apt install ncurses-term unter Ubuntu 24.04 keinen xterm-ghostty-Eintrag erzeugen, unabhängig davon, wie oft Sie den Befehl ausführen. 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.src

-t im zweiten Befehl weist ein Pseudoterminal zu. Dadurch kann sudo zur Eingabe des Passworts auffordern. Ohne diese Option beendet sich sudo möglicherweise mit sudo: no tty present and no askpass program specified.

Der Emulator übernimmt die Übertragung

Einige Emulatoren enthalten ein Hilfsprogramm, das Fix 2 für Sie ausführt. kitty verfügt über ein ssh-Kitten: kitten ssh myserver stellt die Verbindung her und kopiert die Terminfo von kitty 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 enthält eine Shell-Integration (ssh-env und ssh-terminfo) sowie eine +ssh-Aktion, die beide Fixes automatisiert.

Diese Hilfsprogramme führen dieselben Befehle aus, die Sie gerade manuell ausgeführt haben. Die manuelle Form bleibt dennoch wichtig, weil das Hilfsprogramm nicht eingreifen kann, wenn die Verbindung an einer anderen Stelle beginnt, etwa auf einem Jump-Host oder innerhalb eines Skripts.

Wenn der Fehler zurückkehrt

Unter sudo -i. Eine Login-Shell als root hat HOME=/root, und sudo bewahrt Ihr TERM. ncurses sucht nun in /root/.terminfo. Dieses Verzeichnis enthält Ihren Eintrag nicht, daher tritt der Fehler nur für root erneut auf. Prüfen Sie dies mit sudo -i env und lesen Sie die Zeilen HOME und TERM. Installieren Sie den Eintrag im Systemverzeichnis oder legen Sie eine Kopie in /root/.terminfo ab.

In 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 und möglicherweise tmux-256color nicht. Daher 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 besitzt. Eine Terminal-Arbeitsumgebung auf Basis von tmux verbirgt dieses Problem, bis Sie sich eines Tages an einen Host anhängen, den Sie noch nicht korrigiert haben.

Auf einem neuen Server. ~/.terminfo gilt pro Benutzerkonto und pro Rechner. Daher ist ein neu erstellter VPS wieder leer.

Die Anzeige funktioniert, aber die Tasten verhalten sich falsch. Wenn die Anzeige korrekt ist, aber Home, End oder die Funktionstasten unerwartete Zeichen einfügen, wurde ein Eintrag ermittelt, der nicht zu Ihrem Terminal passt. Die Tastensequenzen stammen aus demselben terminfo-Eintrag wie die Anzeigeeigenschaften. Ein ähnlicher Eintrag liefert daher nur ähnliche Tastensequenzen. Das ist normalerweise das Ergebnis von Korrektur 1 bei einem Emulator, dessen Tastensequenzen von xterm abweichen. Korrektur 2 ist in diesem Fall die richtige Lösung, weil nur der tatsächliche Eintrag Ihres Emulators die korrekten Sequenzen enthält.

FAQ

Warum wird über SSH nur „unknown terminal type“ angezeigt?

Die Datenbank, die den Eintrag Ihres Terminals enthalten muss, befindet sich auf dem Server. Ihr Emulator installiert seine Beschreibung auf dem Rechner, auf dem er ausgeführt wird. Lokale Programme finden sie dort ohne weiteres Zutun. SSH überträgt nur den Wert von TERM, da das Protokoll diesen Namen mit der Pseudo-Terminal-Anforderung übermittelt. Die entfernte ncurses-Installation sucht den Namen in der entfernten Datenbank und findet ihn nicht. Daher schlägt initscr fehl und das Programm wird beendet.

Kann ich das ohne root auf dem Server beheben?

Ja. ncurses durchsucht $HOME/.terminfo vor allen Systemverzeichnissen. Ein Eintrag dort reicht daher für Ihr Konto aus. Führen Sie infocmp -x | ssh user@host -- tic -x - einmal pro Server aus. tic schreibt in Ihr Home-Verzeichnis, wenn der Schreibzugriff auf den Systempfad nicht möglich ist. Das ist bei einem nicht privilegierten Konto der Normalfall. Melden Sie sich an und führen Sie tput longname aus, um zu prüfen, ob die Auflösung jetzt funktioniert.

Welche Nachteile hat es, TERM=xterm-256color für einen Host festzulegen?

Alle Fähigkeiten, die Ihr Emulator zusätzlich zum Eintrag xterm-256color beschreibt, gehen verloren. Dazu gehören beispielsweise 24-Bit-Farben über RGB und formatierte Unterstreichungen über Smulx. Programme können diese Fähigkeiten nicht erkennen und verwenden daher den nächstliegenden Fallback. 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 herabgestuft, die bereits funktioniert haben.

Warum tritt der Fehler nach sudo -i wieder auf?

sudo -i startet mit HOME=/root eine Login-Shell als root und behält dabei Ihren Wert TERM bei. ncurses durchsucht dann /root/.terminfo statt Ihres eigenen Home-Verzeichnisses und findet dort nichts. Deshalb sieht root 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 oder kopieren Sie ihn nach /root/.terminfo.

Behebt apt install ncurses-term das Problem immer?

Nein. Der Befehl fügt nur die Einträge hinzu, die in der von Ihrer Distribution bereitgestellten ncurses-Version vorhanden waren. Ubuntu 24.04 liefert ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, Stand August 2026). Der Eintrag für Ghostty wurde jedoch erst in ncurses 6.5-20241228 upstream hinzugefügt. Daher kann dieses Paket ihn nicht enthalten. Prüfen Sie mit tput -T <name> longname, bevor Sie sich auf das Paket verlassen. Wenn weiterhin ein unbekanntes Terminal gemeldet wird, stellen Sie den Eintrag selbst bereit.