SSD Nodes Learn Hosting plans →
Gidsen Matt ConnorDoor Matt Connor

Oplossing voor 'unknown terminal type' bij SSH

Krijgt u de foutmelding 'unknown terminal type' tijdens een SSH-sessie? Los dit op zonder root-toegang door een eigen terminfo-vermelding in uw thuismap te compileren.

Verified Every command ran end-to-end on a fresh Ubuntu 24.04 server, August 13, 2026.

Wat "unknown terminal type" betekent

Een "unknown terminal type"-fout via SSH betekent dat de naam in TERM geen overeenkomstige vermelding heeft in de terminfo-database op de server. Uw emulator stelt die naam in op uw laptop. De database die deze moet herkennen, bevindt zich op de externe machine. Wanneer de opzoekactie mislukt, stopt elk curses-programma op die server voordat het iets tekent, omdat het geen beschrijving heeft van wat uw terminal kan.

De oplossing die alle functies van uw emulator behoudt, is één commando: compileer uw eigen terminfo-vermelding naar ~/.terminfo op de server. Bij een standaard build, zoals die van Debian, doorzoekt ncurses uw home-directory vóór elke systeemdirectory (alleen een $TERMINFO-variabele, indien ingesteld, wordt eerder gecontroleerd). Hiervoor is geen root-toegang nodig en het verandert niets voor andere gebruikers. Die opzoekactie in de home-directory is optioneel in ncurses, en daarom is de controle na de oplossing van belang.

TERM is een naam, terminfo is de database

TERM bevat één string, en die string is enkel een sleutel. terminfo is een gecompileerde database met terminalbeschrijvingen, en de sleutel bepaalt hoe een programma de juiste beschrijving vindt. Een beschrijving legt vast hoeveel kleuren de terminal ondersteunt, welke bytes de cursor naar rij 12 kolom 40 verplaatsen, welke bytes de F5-toets verstuurt en of de terminal een gestileerde onderstreping kan tekenen. ncurses, de bibliotheek waarop vrijwel elke tekstgebaseerde gebruikersinterface op Linux is gebouwd, leest deze beschrijving bij het opstarten. Programma's zoals top, less, nano en watch kunnen zonder deze informatie het scherm niet opbouwen.

Bekijk uw eigen invoer:

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

tput longname toont de leesbare beschrijving van wat TERM benoemt. Voor xterm-256color print het:

xterm with 256 colors

infocmp -1 decompileert de invoer en print één eigenschap per regel. Het laat uitgebreide (door de gebruiker gedefinieerde) eigenschappen weg, tenzij u -x toevoegt, zoals in infocmp -1 -x. Als beide commando's werken, kent de database op deze machine deze terminal. Dat is de status die u ook aan de andere kant van een SSH-verbinding nodig heeft.

Waarom dit alleen via SSH optreedt

SSH verstuurt enkel de naam en niets anders. Wanneer de client om een pseudo-terminal vraagt, reist TERM mee met dat verzoek. De handleiding van OpenSSH is expliciet: "de TERM-omgevingsvariabele wordt altijd verzonden wanneer een pseudo-terminal wordt aangevraagd, aangezien dit vereist is door het protocol". Uw login-shell op de VPS ontvangt dus TERM=xterm-ghostty, of xterm-kitty, of welke naam uw emulator ook gebruikt. De beschrijving achter die naam blijft op uw laptop staan, in de database van uw laptop. Een server die gebouwd is voordat uw emulator bestond, heeft nog nooit van die naam gehoord. Niets in de SSH-verbinding zelf kopieert terminalbeschrijvingen, en dat is een bewuste keuze: het protocol draagt een naam, geen dump van mogelijkheden.

Reproduceer de fout op uw eigen machine met een naam die gegarandeerd niet bestaat:

TERM=xterm-nosuchthing tput colors
echo "$?"
tput: unknown terminal "xterm-nosuchthing"

De exit-status is 3, wat de handleiding van tput documenteert als een "niet-herkend terminaltype". Elk curses-programma voert dezelfde opzoekactie uit, dus één ontbrekende naam produceert een andere melding bij elk programma, terwijl er één enkele oorzaak achter zit. nano stopt met Error opening terminal: xterm-nosuchthing., de standaard ncurses-foutmelding wanneer het bij het opstarten geen beschrijving kan laden. vim print E558: Terminal entry not found in terminfo. less print WARNING: terminal is not fully functional. Een pager die half werkt en een editor die weigert te starten lijken op ongerelateerde bugs. Het is hetzelfde ontbrekende bestand.

Waar ncurses zoekt naar de entry

ncurses doorzoekt locaties in een vaste volgorde, zoals gedocumenteerd in terminfo(5):

  1. $TERMINFO, indien ingesteld. Dit wordt als eerste gecontroleerd.
  2. $HOME/.terminfo. De handleiding noemt dit "een optionele functie die volledig uit de library weggelaten kan zijn", of beperkt is zodat bevoorrechte programma's deze niet per ongeluk gebruiken.
  3. elke directory die vermeld staat in $TERMINFO_DIRS.
  4. de gecompileerde locaties, die op Debian en Ubuntu /etc/terminfo, /lib/terminfo en /usr/share/terminfo omvatten.

Voer infocmp -D uit op de server om de lijst af te drukken die de eigen ncurses-build gebruikt, in plaats van te vertrouwen op de bovenstaande paden. Stap 2 is de kern van de oplossing. De ncurses-build van Debian schakelt dit niet uit, en waar dit aanwezig is, wordt uw home-directory doorzocht vóór elke systeemdirectory. Eén bestand onder ~/.terminfo lost de lookup voor uw account dus op zonder pakketinstallatie en zonder root-rechten. Het uitvoeren van tput longname na de correctie laat zien of de build van uw server dit respecteert. De enige uitzondering is stap 1: als echo "$TERMINFO" iets afdrukt op de server, wordt die locatie als eerste gecontroleerd en krijgt een entry met dezelfde naam daar voorrang op die van u.

Oplossing 1: gebruik een TERM die de server al kent

De snelste manier om de blokkade op te heffen is door voor één verbinding een andere terminalnaam op te geven:

TERM=xterm-256color ssh user@203.0.113.10

Maak dit permanent voor die host in ~/.ssh/config op uw laptop:

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

Het gebruik van SetEnv om TERM te overschrijven vereist OpenSSH 8.7 of nieuwer op de client, uitgebracht in augustus 2021. Oudere clients sturen de TERM van uw eigen emulator, ongeacht deze regel. TERM is de enige variabele waarvoor geen toestemming van de server nodig is: de handleiding stelt: "Net als bij SendEnv, met uitzondering van de TERM-variabele, moet de server bereid zijn de omgevingsvariabele te accepteren". Dit werkt dus zelfs tegen een beveiligde sshd zonder enige AcceptEnv-regel.

Wat dit kost: alles wat uw emulator beschrijft buiten de standaard xterm-256color. Dit omvat 24-bits kleur die wordt geadverteerd via de RGB-mogelijkheid en gestileerde onderstrepingen via Smulx. Programma's die afhankelijk zijn van de terminfo-vermelding kunnen deze mogelijkheden niet langer zien, dus vallen ze terug op 256 kleuren en een standaard onderstreping, tenzij u ze configureert om de sequenties alsnog te sturen. Vim kan bijvoorbeeld nog steeds 24-bits kleur weergeven met set termguicolors, omdat de ingebouwde t_8f- en t_8b-sequenties voor de meeste terminals werken. Het scherm werkt. Het is simpelweg minder capabel dan de terminal die u heeft gekozen.

Los dit niet op door export TERM=xterm-256color toe te voegen aan uw .bashrc op de server. Dat bestand wordt uitgevoerd bij elke verbinding, inclusief verbindingen vanaf een terminal waarvan de server de naam wel kent, waardoor sessies die al in orde waren worden gedegradeerd. Houd de overschrijving op de client, waar u weet welke emulator u gebruikt.

Oplossing 2: stuur uw terminfo-entry eenmalig naar de server

Dit is de oplossing waarmee uw emulator intact blijft. Decompileer de entry lokaal, stuur deze via SSH door en compileer deze aan de ontvangende kant:

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

infocmp -x print de entry voor uw huidige TERM als brontekst, inclusief uitgebreide (door de gebruiker gedefinieerde) functionaliteiten. tic -x compileert die brontekst terug naar een binaire beschrijving op de server. De -x aan beide kanten is van belang, omdat zonder deze vlag functionaliteiten zoals Smulx tijdens het transport verloren gaan en u een gedegradeerde kopie van uw eigen terminal verstuurt.

tic schrijft naar de systeemmappen wanneer dit mogelijk is, en valt terug op $HOME/.terminfo wanneer de gebruiker daar geen schrijfrechten heeft. Een standaardaccount op een VPS gebruikt de thuismap, wat precies is wat u wilt. U kunt ook de doelbestemming opgeven:

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

De aanhalingstekens rond ~/.terminfo zijn geen versiering. ssh voegt de commando-onderdelen samen tot één string en geeft deze door aan de externe shell; een niet-gequote ~ wordt namelijk eerst door uw lokale shell geëxpandeerd. U stuurt dan een letterlijke /home/yourname/.terminfo naar een machine waar uw account mogelijk een andere naam heeft. tic faalt dan met een toegangsrechtenfout, of schrijft naar een pad dat ncurses nooit doorzoekt. Quote de tilde zodat de externe shell deze expandeert.

Log in en controleer:

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

tput longname dat de beschrijving van uw terminal wordt geprint, betekent dat het opzoeken nu slaagt, en ls toont het gecompileerde bestand in een submap die vernoemd is naar de eerste letter van de terminalnaam. Voer daarna top uit, of watch -n1 uptime, die de weergave ververst via dezelfde bibliotheek, om te bevestigen dat een echt curses-programma het scherm correct tekent.

Wat het kost: één stap per server, en de entry bevindt zich in de thuismap van één account op één machine. Bouw de VPS opnieuw op en de entry is verdwenen. Voeg het commando toe aan de tool die u gebruikt voor het provisioneren en beheren van meerdere servers tegelijk, zodat een nieuwe host direct met de gecompileerde entry wordt opgeleverd.

Oplossing 3: installeer de uitgebreide terminfo-database

Als u root-toegang heeft en wilt dat de naam voor elk account op de server wordt opgelost:

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

ncurses-term bevat de terminalbeschrijvingen die bij de basisinstallatie ontbreken. Dit lost de naam op voor root en voor elke andere gebruiker, wat bij oplossing 2 niet het geval is.

Dit helpt alleen als de entry van uw terminal bestaat in de ncurses-release die uw distributie meelevert, dus controleer dit in plaats van ervan uit te gaan. Ubuntu 24.04 levert ncurses-bin 6.4+20240113-1ubuntu2.2 (per november 2026). De entry van Ghostty is upstream toegevoegd in ncurses 6.5-20241228, wat nieuwer is; daarom kan apt install ncurses-term op Ubuntu 24.04 geen xterm-ghostty-entry genereren, hoe vaak u het ook uitvoert. tput -T <name> longname is de controle: dit drukt de beschrijving af als de entry aanwezig is, en unknown terminal met exit-status 3 als dat niet zo is.

Om een enkele entry systeembreed te installeren in plaats van het hele pakket, kopieert u de broncode en compileert u deze 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

De -t in het tweede commando wijst een pseudo-terminal toe, zodat sudo om het wachtwoord kan vragen. Zonder dit wijst ssh geen terminal toe voor een extern commando en stopt sudo met sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper wanneer er een wachtwoord vereist is. Die foutmelding heeft betrekking op de ontbrekende tty, niet op terminfo.

Laat de emulator de overdracht uitvoeren

Sommige emulators leveren een hulpprogramma mee dat correctie 2 voor u uitvoert. kitty heeft een ssh kitten: kitten ssh myserver maakt verbinding en kopieert de terminfo van kitty automatisch naar de externe host. De documentatie geeft ook de handmatige vorm, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, waarbij de tilde is geëscaped om de hierboven beschreven reden. Ghostty documenteert infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - en levert sinds versie 1.2.0 opt-in shell-integratiefuncties (ssh-env en ssh-terminfo) die beide correcties automatiseren. Ghostty 1.4.0, uitgebracht op 27 oktober 2026, voegt een ghostty +ssh wrapper toe die de 1.3.x releases niet hebben, en de twee opt-in functies roepen deze nu aan. Het installeert de meegeleverde terminfo van Ghostty op de externe host voordat de verbinding wordt gemaakt, en valt terug op TERM=xterm-256color wanneer die installatie mislukt, bijvoorbeeld wanneer de server geen tic heeft. In 1.4 stopt ssh-env ook met het overschrijven van SetEnv regels in ~/.ssh/config, waardoor een per-host override van correctie 1 wordt gerespecteerd.

Deze hulpprogramma's voeren dezelfde commando's uit die u zojuist handmatig hebt uitgevoerd. Het kennen van de handmatige vorm blijft belangrijk, omdat het hulpprogramma niet kan ingrijpen wanneer de verbinding ergens anders start, op een jump host of binnen een script.

Wanneer de fout terugkeert

Onder sudo -i. Een login-shell als root heeft HOME=/root, en sudo behoudt uw TERM. ncurses doorzoekt nu /root/.terminfo, dat uw invoer niet bevat, waardoor de foutmelding alleen voor root terugkeert. Bevestig dit met sudo -i env en lees de HOME en TERM regels. Installeer de invoer in de systeemdirectory. Een kopie in /root/.terminfo kan ook werken, maar ncurses kan de opzoeking in de homedirectory voor bevoorrechte processen beperken, dus voer tput longname uit als root om dit te bevestigen.

Binnen tmux of screen. Deze stellen hun eigen TERM in voor de programma's die erin draaien, meestal screen-256color of tmux-256color. Een oudere server kent screen-256color en kent mogelijk tmux-256color niet, waardoor de buitenste shell correct werkt terwijl alles binnen de sessie faalt. Dezelfde oorzaak, andere naam. Voer tput -T tmux-256color longname uit op de server om te zien welke van de twee aanwezig is. Een terminalwerkbank gebouwd rond tmux verbergt dit totdat u op een dag verbindt met een host die u nog niet heeft hersteld.

Op een nieuwe server. ~/.terminfo is per account en per machine, dus een opnieuw geïnstalleerde VPS begint weer leeg.

Scherm tekent, toetsen werken niet goed. Als het beeld in orde is maar Home, End of de functietoetsen vreemde tekens invoegen, dan is de naam opgelost naar een invoer die niet overeenkomt met uw terminal. Toetssequenties komen uit dezelfde terminfo-invoer als de tekenmogelijkheden, dus een benaderende invoer geeft benaderende toetsen. Dat is het gebruikelijke resultaat van fix 1 op een emulator waarvan de toetssequenties afwijken van xterm. Fix 2 is de meest zuivere oplossing, omdat de echte invoer van uw emulator direct de juiste sequenties voor elk programma bevat. Het is niet de enige route: de documentatie van Vim stelt dat u "de key code kunt wijzigen met het :set commando", en Vim vraagt bij het opstarten direct aan een recente xterm om zijn key codes in plaats van alleen op de invoer te vertrouwen.

FAQ

Waarom zie ik alleen "unknown terminal type" via SSH?

Omdat de database die de vermelding van uw terminal moet bevatten, zich op de server bevindt. Uw emulator installeert de beschrijving op de machine waarop deze draait, zodat lokale programma's deze zonder enige inspanning van uw kant vinden. SSH verstuurt alleen de waarde van TERM, aangezien het protocol die naam meeneemt met het pseudo-terminalverzoek. De externe ncurses zoekt de naam op in de externe database en vindt niets, waardoor initscr faalt en het programma stopt.

Kan ik dit oplossen zonder root-toegang op de server?

Ja, op een standaard build zoals die van Debian. ncurses doorzoekt $HOME/.terminfo vóór elke systeemmap, en alleen een $TERMINFO-variabele die op de server is ingesteld wordt eerder gecontroleerd, dus in het normale geval is een vermelding daar voldoende voor uw account. Het opzoeken in de thuismap is optioneel in ncurses, wat de reden is waarom de tput longname-controle hieronder van belang is. Voer infocmp -x | ssh user@host -- tic -x - één keer per server uit. tic schrijft naar uw thuismap wanneer het niet naar het systeempad kan schrijven, wat het normale geval is voor een account zonder privileges. Log in en voer tput longname uit om te bevestigen dat het opzoeken nu slaagt.

Wat verlies ik door TERM=xterm-256color in te stellen voor een host?

Elke mogelijkheid die uw emulator beschrijft buiten de xterm-256color-vermelding, zoals 24-bit kleur via RGB en gestileerde onderstrepingen via Smulx. Programma's die afhankelijk zijn van de terminfo-vermelding kunnen die mogelijkheden niet zien, dus gebruiken ze de dichtstbijzijnde fallback tenzij u ze anders configureert, zoals de termguicolors-optie van Vim doet voor kleur. Functietoetsreeksen kunnen ook afwijken van uw werkelijke terminal. Plaats de instelling op de client in ~/.ssh/config in plaats van in een .bashrc op de server, wat sessies van terminals die al werkten zou degraderen.

Waarom komt de fout terug na sudo -i?

sudo -i start een login-shell als root met HOME=/root, terwijl uw TERM-waarde behouden blijft. ncurses doorzoekt vervolgens /root/.terminfo in plaats van uw eigen thuismap en vindt niets, dus ziet root dezelfde fout die uw account niet langer ziet. Voer sudo -i env uit en controleer de HOME- en TERM-regels. Compileer de vermelding in de systeemmap met sudo tic -x -o /usr/share/terminfo. Een kopie in /root/.terminfo kan ook werken, maar ncurses kan het opzoeken in de thuismap voor bevoorrechte processen beperken, dus bevestig dit met tput longname als root.

Lost apt install ncurses-term het altijd op?

Nee. Het voegt alleen de vermeldingen toe die bestonden in de ncurses-release die uw distributie heeft verpakt. Ubuntu 24.04 levert ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, per november 2026), en de vermelding van Ghostty werd upstream toegevoegd in ncurses 6.5-20241228, dus dat pakket kan deze niet bevatten. Controleer met tput -T <name> longname voordat u op het pakket vertrouwt, en lever de vermelding zelf aan wanneer de controle nog steeds een onbekende terminal rapporteert.

Was dit artikel nuttig?

#terminfo#ssh#ncurses#tput#terminal