SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor

Come risolvere "unknown terminal type" via SSH

L'errore "unknown terminal type" indica che il server non conosce TERM. Compila una voce terminfo nella home con un comando, senza privilegi root.

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

Che cosa significa "tipo di terminale sconosciuto"

Un errore relativo a un tipo di terminale sconosciuto tramite SSH indica che il nome in TERM non ha una voce corrispondente nel database terminfo sul server. È l'emulatore sul laptop a impostare quel nome. Il database che deve riconoscerlo risiede sulla macchina remota. Quando la ricerca fallisce, tutti i programmi curses su quel server si interrompono prima di visualizzare qualsiasi elemento, perché non dispongono della descrizione delle funzionalità del terminale.

La soluzione che conserva tutte le funzionalità dell'emulatore consiste nell'eseguire un solo comando: compilare la propria voce terminfo in ~/.terminfo sul server. In una configurazione standard, come quella di Debian, ncurses cerca nella directory home dell'utente prima di consultare qualsiasi directory di sistema; viene controllata prima soltanto la variabile $TERMINFO, se impostata. Non servono quindi privilegi root e non cambia nulla per gli altri utenti. La ricerca nella directory home è opzionale in ncurses, quindi è importante eseguire la verifica dopo la correzione.

TERM è un nome, terminfo è il database

TERM contiene una stringa, che rappresenta soltanto una chiave. terminfo è un database compilato di descrizioni dei terminali e la chiave consente a un programma di trovare quella corretta. Una descrizione indica quanti colori supporta il terminale, quali byte spostano il cursore alla riga 12 e alla colonna 40, quali byte invia il tasto F5 e se il terminale può disegnare un carattere di sottolineatura con stile. ncurses, la libreria su cui si basa quasi ogni interfaccia utente testuale in Linux, legge questa descrizione all'avvio. Programmi come top, less, nano e watch non possono visualizzare nemmeno una schermata senza di essa.

Controlla la tua voce:

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

tput longname stampa la descrizione leggibile del nome indicato da TERM. Per xterm-256color stampa:

xterm with 256 colors

infocmp -1 decompila la voce e stampa una funzionalità per riga. Esclude le funzionalità estese, definite dall'utente, a meno che non si aggiunga -x, come in infocmp -1 -x. Se entrambi i comandi funzionano, il database presente su questa macchina conosce questo terminale. È la stessa condizione necessaria anche dall'altra parte di una connessione SSH.

Perché si rompe solo tramite SSH

SSH invia il nome e nient'altro. Quando il client richiede uno pseudo-terminale, TERM viene trasmesso insieme a quella richiesta. Il manuale di OpenSSH è esplicito: "the TERM environment variable is always sent whenever a pseudo-terminal is requested as it is required by the protocol". La shell di login sulla VPS riceve quindi TERM=xterm-ghostty, xterm-kitty oppure qualunque altro nome usi il tuo emulatore. La descrizione associata a quel nome resta sul laptop, nel database del laptop. Un server realizzato prima dell'emulatore non ha mai riconosciuto quel nome. Niente nella connessione SSH stessa copia le descrizioni dei terminali, e questa è una scelta deliberata: il protocollo trasporta un nome, non un insieme completo di funzionalità.

Riproduci il problema sulla tua macchina usando un nome che certamente non esiste:

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

Il codice di uscita è 3, che il manuale di tput documenta come "unrecognized terminal type". Ogni programma curses esegue la stessa ricerca, quindi un solo nome mancante produce un messaggio diverso in ciascun programma, con un'unica causa comune. nano si interrompe con Error opening terminal: xterm-nosuchthing., l'errore standard di ncurses quando non riesce a caricare una descrizione all'avvio. vim stampa E558: Terminal entry not found in terminfo. less stampa WARNING: terminal is not fully functional. Un pager che funziona solo parzialmente e un editor che rifiuta di avviarsi sembrano problemi non correlati. In realtà dipendono dallo stesso file mancante.

Dove ncurses cerca la voce

ncurses esegue la ricerca in un ordine fisso, documentato in terminfo(5):

  1. $TERMINFO, se impostato. Viene controllato per primo.
  2. $HOME/.terminfo. Il manuale lo descrive come «una funzionalità opzionale che può essere omessa completamente dalla libreria» oppure limitata in modo che i programmi con privilegi non la utilizzino accidentalmente.
  3. tutte le directory elencate in $TERMINFO_DIRS.
  4. i percorsi compilati nella libreria, che su Debian e Ubuntu includono /etc/terminfo, /lib/terminfo e /usr/share/terminfo.

Esegui infocmp -D sul server per stampare l'elenco utilizzato dalla build di ncurses presente sul server, invece di affidarti ai percorsi indicati sopra. Il passaggio 2 è l'elemento determinante. La build di ncurses di Debian non lo disabilita e, quando è presente, la directory home viene cercata prima di qualsiasi directory di sistema. Di conseguenza, un solo file in ~/.terminfo corregge la ricerca per il tuo account, senza installare pacchetti e senza usare root. Eseguendo tput longname dopo la correzione puoi verificare se la build del server la supporta. L'unica eccezione è il passaggio 1: se echo "$TERMINFO" stampa un valore sul server, quella posizione viene controllata per prima e una voce con lo stesso nome presente lì ha la precedenza sulla tua.

Correzione 1: usare un TERM già riconosciuto dal server

Il modo più rapido per sbloccare la situazione consiste nell'indicare un terminale diverso per una singola connessione:

TERM=xterm-256color ssh user@203.0.113.10

Per renderlo permanente per quell'host, aggiungilo a ~/.ssh/config sul laptop:

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

Per usare SetEnv per sovrascrivere TERM, il client deve eseguire OpenSSH 8.7 o una versione successiva, rilasciata nell'agosto 2021. I client meno recenti inviano comunque il valore TERM del tuo emulatore, indipendentemente da questa riga. TERM è l'unica variabile per cui non serve l'autorizzazione del server: il manuale specifica che «Analogamente a SendEnv, con l'eccezione della variabile TERM, il server deve essere configurato per accettare la variabile d'ambiente». Pertanto funziona anche con un sshd con configurazione restrittiva e senza alcuna riga AcceptEnv.

Il costo è la perdita di tutte le caratteristiche descritte dal tuo emulatore oltre il semplice xterm-256color. Tra queste rientrano il colore a 24 bit pubblicizzato tramite la capability RGB e le sottolineature stilizzate tramite Smulx. I programmi che si basano sulla voce terminfo non possono più rilevare queste capability. Di conseguenza, usano 256 colori e una sottolineatura semplice, a meno che tu non li configuri per inviare comunque le sequenze. Per esempio, Vim può continuare a visualizzare colori a 24 bit con set termguicolors, perché le sequenze t_8f e t_8b integrate funzionano con la maggior parte dei terminali. La visualizzazione funziona. È semplicemente meno completa rispetto a quella del terminale scelto.

Non risolvere il problema aggiungendo export TERM=xterm-256color a .bashrc sul server. Quel file viene eseguito per ogni connessione, comprese quelle provenienti da un terminale il cui nome è riconosciuto dal server. In questo modo ridurresti le funzionalità anche nelle sessioni che funzionavano già correttamente. Mantieni la sovrascrittura sul client, dove sai quale emulatore stai utilizzando.

Correzione 2: inviare una volta la voce terminfo al server

Questa correzione mantiene intatto il tuo emulatore. Decompila localmente la voce, inoltrala tramite SSH e compilala sul server remoto:

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

infocmp -x stampa la voce corrispondente al tuo TERM corrente come testo sorgente, incluse le funzionalità estese, definite dall'utente. tic -x ricompila il sorgente in una descrizione binaria sul server. -x su entrambi i lati è importante, perché senza questa opzione funzionalità come Smulx vengono eliminate durante il trasferimento e sul server viene installata una copia con capacità ridotte del terminale originale.

tic scrive nella directory di sistema quando possibile e usa $HOME/.terminfo come fallback quando l'utente non dispone dei permessi di scrittura. Un account ordinario su un VPS usa la directory home, che è la scelta corretta. Puoi anche specificare la destinazione:

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

Le virgolette intorno a ~/.terminfo sono necessarie. ssh unisce le parole del comando in un'unica stringa e la passa alla shell remota, quindi un ~ non racchiuso tra virgolette viene espanso prima dalla shell locale. In questo modo invii un /home/yourname/.terminfo letterale a una macchina in cui l'account potrebbe avere un nome diverso. tic restituisce un errore di autorizzazione oppure scrive in un percorso che ncurses non cerca. Racchiudi la tilde tra virgolette e lascia che sia la shell remota a espanderla.

Accedi e verifica:

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

La stampa della descrizione del terminale da parte di tput longname indica che la ricerca ora ha esito positivo; ls mostra il file compilato in una sottodirectory denominata con la prima lettera del nome del terminale. Esegui quindi top oppure watch -n1 uptime, che ridisegna l'output usando la stessa libreria, per verificare che un programma curses reale visualizzi correttamente lo schermo.

Costo operativo: un passaggio per ogni server, con la voce memorizzata nella directory home dell'account su una sola macchina. Se ricrei il VPS, la voce viene eliminata. Inserisci il comando nello strumento che usi per predisporre e gestire più server contemporaneamente, così ogni nuovo host viene fornito con la voce già compilata.

Correzione 3: installare il database terminfo esteso

Se disponi dell'account root e vuoi che il nome venga risolto per ogni account sul server:

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

ncurses-term contiene le descrizioni dei terminali escluse dall'installazione di base. Risolve il problema del nome per root e per tutti gli altri utenti, a differenza della correzione 2.

Funziona solo se la voce del terminale è presente nella versione di ncurses inclusa nella distribuzione. Verificalo invece di dare per scontato che lo sia. Ubuntu 24.04 include ncurses-bin 6.4+20240113-1ubuntu2.2 (a novembre 2026). La voce di Ghostty è stata aggiunta upstream in ncurses 6.5-20241228, che è più recente; pertanto, su Ubuntu 24.04, apt install ncurses-term non può produrre una voce xterm-ghostty, indipendentemente dal numero di volte in cui lo esegui. tput -T <name> longname esegue il controllo: stampa la descrizione quando la voce è presente e restituisce unknown terminal con codice di uscita 3 quando non lo è.

Per installare una singola voce a livello di sistema invece dell'intero pacchetto, copia il sorgente e compilalo come 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 nel secondo comando assegna un terminale pseudoterminale, così sudo può richiedere la password. Senza questa opzione, ssh non assegna alcun terminale a un comando remoto e sudo si interrompe con sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper quando deve richiedere una password. L'errore riguarda l'assenza del tty, non terminfo.

Lascia che sia l’emulatore a eseguire il trasferimento

Alcuni emulatori includono un’utilità che esegue automaticamente la correzione 2. kitty dispone di un ssh kitten: kitten ssh myserver stabilisce la connessione e copia automaticamente il terminfo di kitty sull’host remoto. La documentazione descrive anche la forma manuale, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, con il carattere tilde protetto per il motivo descritto sopra. Ghostty documenta infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - e, a partire dalla versione 1.2.0, include funzionalità opzionali di integrazione con la shell (ssh-env e ssh-terminfo) che automatizzano entrambe le correzioni. Ghostty 1.4.0, rilasciato il 27 ottobre 2026, aggiunge un wrapper ghostty +ssh che non era presente nelle release 1.3.x; ora le due funzionalità opzionali lo utilizzano. Il wrapper installa il terminfo incluso in Ghostty sull’host remoto prima di stabilire la connessione e, se l’installazione non riesce, ricorre a TERM=xterm-256color, ad esempio quando sul server non è disponibile tic. Nella versione 1.4, ssh-env smette inoltre di sovrascrivere le righe SetEnv in ~/.ssh/config, quindi viene rispettata una configurazione specifica per l’host definita con la correzione 1.

Queste utilità eseguono gli stessi comandi appena eseguiti manualmente. Conoscere la procedura manuale resta importante, perché l’utilità non può intervenire quando la connessione viene avviata altrove, su un jump host o all’interno di uno script.

Quando l’errore ricompare

Con sudo -i. Una shell di login come root ha HOME=/root e sudo conserva il tuo TERM. A questo punto ncurses cerca /root/.terminfo, che non contiene la tua voce, quindi l’errore si ripresenta solo per root. Verifica con sudo -i env e leggi le righe HOME e TERM. Installa la voce nella directory di sistema. Può funzionare anche una copia in /root/.terminfo, ma ncurses può limitare la ricerca nella directory home per i processi privilegiati; esegui quindi tput longname come root per confermare.

All'interno di tmux o screen. Questi programmi impostano un proprio TERM per i programmi eseguiti al loro interno, in genere screen-256color o tmux-256color. Un server meno recente riconosce screen-256color e potrebbe non riconoscere tmux-256color; la shell esterna funziona, mentre tutto ciò che viene eseguito nella sessione non funziona. La causa è la stessa, ma il nome è diverso. Esegui tput -T tmux-256color longname sul server per verificare quale dei due è disponibile. Un ambiente di lavoro per terminale basato su tmux nasconde il problema finché non ti connetti a un host che non hai ancora corretto.

Su un server appena installato. ~/.terminfo è specifico dell'account e della macchina, quindi un VPS ricreato riparte nuovamente da una configurazione vuota.

Lo schermo viene visualizzato, ma i tasti non funzionano correttamente. Se la visualizzazione è corretta, ma Home, End o i tasti funzione inseriscono caratteri indesiderati, il nome è stato associato a una voce che non corrisponde al tuo terminale. Le sequenze dei tasti provengono dalla stessa voce terminfo delle capacità di visualizzazione; una voce approssimativa produce quindi sequenze dei tasti approssimative. Questo è il risultato tipico della correzione 1 su un emulatore le cui sequenze dei tasti differiscono da xterm. La correzione 2 è la soluzione più pulita, perché la voce effettiva del tuo emulatore contiene le sequenze corrette per tutti i programmi. Non è l'unica possibilità: la documentazione di Vim indica che puoi «modificare il codice del tasto con il comando :set» e, all'avvio, Vim chiede direttamente a un xterm recente i relativi codici dei tasti, invece di affidarsi soltanto alla voce.

FAQ

Perché tramite SSH vedo solo «unknown terminal type»?

Perché il database che deve contenere la voce del terminale si trova sul server. L'emulatore installa la propria descrizione sulla macchina su cui viene eseguito, quindi i programmi locali la trovano senza interventi aggiuntivi. SSH invia solo il valore di TERM, perché il protocollo trasmette quel nome nella richiesta dello pseudo-terminale. ncurses sul sistema remoto cerca il nome nel database remoto, ma non trova nulla; di conseguenza initscr fallisce e il programma si arresta.

Posso risolvere il problema senza avere root sul server?

Sì, in una build standard come quella di Debian. ncurses cerca $HOME/.terminfo prima di qualsiasi directory di sistema e controlla prima soltanto una variabile $TERMINFO impostata sul server; nel caso normale, quindi, è sufficiente inserire una voce in quel percorso per il proprio account. La ricerca nella home directory è facoltativa in ncurses, per questo è importante il controllo tput longname riportato di seguito. Esegui infocmp -x | ssh user@host -- tic -x - una volta per ogni server. tic scrive nella tua home directory quando non può scrivere nel percorso di sistema, che è il comportamento normale per un account senza privilegi. Accedi ed esegui tput longname per verificare che la ricerca ora risolva la voce.

Che cosa perdo impostando TERM=xterm-256color per un host?

Perdi tutte le funzionalità descritte dal tuo emulatore oltre la voce xterm-256color, ad esempio il colore a 24 bit tramite RGB e le sottolineature con stile tramite Smulx. I programmi che si basano sulla voce terminfo non possono vedere queste funzionalità, quindi usano il fallback più vicino, a meno che non vengano configurati diversamente, come fa l'opzione termguicolors di Vim per il colore. Anche le sequenze dei tasti funzione possono differire da quelle del terminale reale. Inserisci l'impostazione nel client, in ~/.ssh/config, non in un .bashrc sul server, perché in quel caso ridurresti le funzionalità delle sessioni avviate da terminali che già funzionavano.

Perché l'errore ricompare dopo sudo -i?

sudo -i avvia una login shell come root con HOME=/root, mantenendo il valore TERM. ncurses cerca quindi in /root/.terminfo invece che nella home directory dell'utente e non trova nulla; root visualizza così lo stesso errore che il tuo account non visualizza più. Esegui sudo -i env e controlla le righe HOME e TERM. Compila la voce nella directory di sistema con sudo tic -x -o /usr/share/terminfo. Può funzionare anche una copia in /root/.terminfo, ma ncurses può limitare la ricerca nella home directory per i processi privilegiati; verifica quindi con tput longname come root.

apt install ncurses-term risolve sempre il problema?

No. Aggiunge soltanto le voci presenti nella versione di ncurses inclusa nella distribuzione. Ubuntu 24.04 include ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, a novembre 2026) e la voce di Ghostty è stata aggiunta upstream in ncurses 6.5-20241228, quindi quel pacchetto non può contenerla. Controlla con tput -T <name> longname prima di affidarti al pacchetto e installa autonomamente la voce se il controllo continua a segnalare un terminale sconosciuto.

Questo articolo ti è stato utile?

#terminfo#ssh#ncurses#tput#terminal