SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como corrigir "unknown terminal type" no SSH

Veja por que o erro "unknown terminal type" ocorre no SSH e instale uma entrada terminfo em ~/.terminfo, sem root e sem alterar o sistema.

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

O que significa "tipo de terminal desconhecido"

Um erro de tipo de terminal desconhecido via SSH significa que o nome em TERM não tem uma entrada correspondente na base de dados terminfo no servidor. O seu emulador define esse nome no seu portátil. A base de dados que tem de o reconhecer está na máquina remota. Quando a consulta falha, todos os programas curses nesse servidor terminam antes de desenhar qualquer coisa, porque não têm uma descrição das capacidades do seu terminal.

A correção que preserva todas as funcionalidades do seu emulador consiste num comando: compile a sua própria entrada terminfo em ~/.terminfo no servidor. Numa compilação padrão, como a do Debian, o ncurses pesquisa o seu diretório pessoal antes de qualquer diretório do sistema (apenas uma variável $TERMINFO, se definida, é verificada primeiro). Por isso, não é necessário ter root e nada é alterado para os outros utilizadores. Essa consulta no diretório pessoal é opcional no ncurses, razão pela qual a verificação após a correção é importante.

TERM é um nome; terminfo é a base de dados

TERM contém uma cadeia, e essa cadeia é apenas uma chave. terminfo é uma base de dados compilada com descrições de terminais, e a chave é usada por um programa para encontrar a descrição correta. Uma descrição regista quantas cores o terminal suporta, quais bytes movem o cursor para a linha 12, coluna 40, quais bytes a tecla F5 envia e se o terminal consegue desenhar um sublinhado com estilo. ncurses, a biblioteca na qual quase todas as interfaces de texto do Linux são construídas, lê essa descrição durante o arranque. Programas como top, less, nano e watch não conseguem apresentar um único ecrã sem ela.

Consulte a sua própria entrada:

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

tput longname apresenta a descrição legível por humanos do que quer que TERM identifique. Para xterm-256color, apresenta:

xterm with 256 colors

infocmp -1 descompila a entrada e apresenta uma capacidade por linha. Omite as capacidades estendidas, definidas pelo utilizador, exceto se adicionar -x, como em infocmp -1 -x. Se ambos os comandos funcionarem, a base de dados desta máquina conhece este terminal. Esse é também o estado necessário no outro lado de uma ligação SSH.

Por que isso só falha via SSH

O SSH envia o nome e nada mais. Quando o cliente solicita um pseudo-terminal, TERM é enviado junto com essa solicitação. O manual do OpenSSH é explícito: "a variável de ambiente TERM é sempre enviada quando um pseudo-terminal é solicitado, pois é necessária para o protocolo". Portanto, o seu shell de login na VPS recebe TERM=xterm-ghostty, ou xterm-kitty, ou qualquer outro nome usado pelo seu emulador. A descrição associada a esse nome permanece no seu laptop, na base de dados do seu laptop. Um servidor criado antes de o seu emulador existir nunca ouviu falar desse nome. Nada na própria ligação SSH copia as descrições de terminal, e isso é intencional: o protocolo transporta um nome, não um inventário de capacidades.

Reproduza a falha na sua própria máquina usando um nome que certamente não existe:

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

O código de saída é 3, que o manual de tput documenta como um "tipo de terminal não reconhecido". Todos os programas que usam curses fazem a mesma consulta. Por isso, um único nome ausente produz uma mensagem diferente em cada programa, embora a causa seja a mesma. nano termina com Error opening terminal: xterm-nosuchthing., a falha padrão do ncurses quando não consegue carregar uma descrição na inicialização. vim imprime E558: Terminal entry not found in terminfo. less imprime WARNING: terminal is not fully functional. Um pager que funciona apenas parcialmente e um editor que se recusa a iniciar parecem problemas não relacionados. Na realidade, são o mesmo ficheiro em falta.

Onde o ncurses procura a entrada

O ncurses pesquisa numa ordem fixa, documentada em terminfo(5):

  1. $TERMINFO, se estiver definida. Esta localização é verificada primeiro.
  2. $HOME/.terminfo. O manual chama-lhe «uma funcionalidade opcional que pode ser totalmente omitida da biblioteca» ou que pode ser limitada para impedir que programas privilegiados a utilizem acidentalmente.
  3. todos os diretórios listados em $TERMINFO_DIRS.
  4. as localizações incorporadas na compilação, que no Debian e no Ubuntu incluem /etc/terminfo, /lib/terminfo e /usr/share/terminfo.

Execute infocmp -D no servidor para apresentar a lista usada pela própria compilação do ncurses, em vez de confiar nos caminhos anteriores. O passo 2 é o essencial. A compilação do ncurses no Debian não o desativa. Quando está presente, o seu diretório pessoal é pesquisado antes de qualquer diretório do sistema. Por isso, um ficheiro em ~/.terminfo corrige a pesquisa para a sua conta, sem instalar pacotes e sem usar root. Execute tput longname depois da correção para confirmar se a compilação do servidor a respeita. A única exceção é o passo 1: se echo "$TERMINFO" apresentar algum valor no servidor, essa localização é verificada primeiro. Uma entrada com o mesmo nome nesse local tem precedência sobre a sua.

Correção 1: use um TERM que o servidor já conhece

A forma mais rápida de desbloquear a situação é indicar um terminal diferente para uma ligação:

TERM=xterm-256color ssh user@203.0.113.10

Torne essa definição permanente para esse host em ~/.ssh/config no seu portátil:

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

Usar SetEnv para substituir TERM requer OpenSSH 8.7 ou posterior no cliente, lançado em agosto de 2021. Os clientes mais antigos enviam sempre o próprio TERM do emulador, independentemente desta linha. TERM é a única variável que não requer autorização do servidor: o manual diz que "Tal como em SendEnv, com a exceção da variável TERM, o servidor tem de estar preparado para aceitar a variável de ambiente". Por isso, isto funciona mesmo com um sshd reforçado, sem qualquer linha AcceptEnv.

Custo: tudo o que o seu emulador descreve para além de xterm-256color simples. Isso inclui a cor de 24 bits anunciada através da capacidade RGB e os sublinhados estilizados através de Smulx. Os programas que dependem da entrada terminfo deixam de ver essas capacidades. Por isso, usam 256 cores e um sublinhado simples, a menos que os configure para enviarem as sequências mesmo assim. O Vim, por exemplo, ainda pode apresentar cores de 24 bits com set termguicolors, porque as sequências t_8f e t_8b incorporadas funcionam com a maioria dos terminais. O ecrã funciona. Apenas tem menos capacidades do que o terminal que escolheu.

Não resolva isto adicionando export TERM=xterm-256color ao seu .bashrc no servidor. Esse ficheiro é executado para todas as ligações, incluindo ligações de um terminal cujo nome o servidor conhece. Assim, degrada sessões que já funcionavam corretamente. Mantenha a substituição no cliente, onde sabe qual é o emulador que está a utilizar.

Correção 2: envie a sua entrada terminfo para o servidor uma vez

Esta é a correção que mantém o seu emulador intacto. Descompile a entrada localmente, envie-a através do SSH e compile-a no servidor:

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

infocmp -x imprime a entrada do seu TERM atual como texto-fonte, incluindo capacidades estendidas (definidas pelo utilizador). tic -x compila esse texto-fonte novamente numa descrição binária no servidor. O -x em ambos os lados é importante, porque, sem ele, capacidades como Smulx são descartadas durante a transferência e é enviada uma cópia degradada do seu próprio terminal.

tic escreve no diretório do sistema quando tem permissão para isso e recorre a $HOME/.terminfo quando o utilizador não tem acesso de escrita nesse diretório. Uma conta normal numa VPS utiliza o diretório pessoal, que é o comportamento pretendido. Também pode indicar o destino:

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

As aspas à volta de ~/.terminfo não são decorativas. ssh junta as palavras do comando numa única cadeia e entrega-a ao shell remoto, por isso um ~ sem aspas é expandido primeiro pelo seu shell local. Em seguida, envia um /home/yourname/.terminfo literal para uma máquina onde a sua conta pode ter outro nome. tic falha com um erro de permissão ou escreve num caminho que o ncurses nunca pesquisa. Coloque as aspas à volta do til e deixe o shell remoto expandi-lo.

Inicie sessão e verifique:

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

tput longname imprimir a descrição do seu terminal significa que a pesquisa foi bem-sucedida, e ls mostra o ficheiro compilado dentro de um subdiretório cujo nome corresponde à primeira letra do nome do terminal. Em seguida, execute top ou watch -n1 uptime, que redesenha o ecrã através da mesma biblioteca, para confirmar que um programa curses real consegue desenhar o ecrã.

O custo é um passo por servidor, e a entrada fica no diretório pessoal de uma conta numa única máquina. Se reconstruir a VPS, a entrada desaparece. Inclua o comando na ferramenta que utiliza para provisionar e gerir vários servidores em simultâneo, para que um novo host já tenha a entrada compilada.

Instalar o banco de dados terminfo estendido

Se tiver root e quiser que o nome seja resolvido para todas as contas no servidor:

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

ncurses-term contém as descrições de terminais que a instalação base não inclui. Ele corrige o nome para root e para todos os outros utilizadores, ao contrário da correção 2.

Isto só ajuda quando a entrada do seu terminal existe na versão do ncurses empacotada pela sua distribuição. Por isso, verifique em vez de presumir. O Ubuntu 24.04 inclui ncurses-bin 6.4+20240113-1ubuntu2.2 (em novembro de 2026). A entrada do Ghostty foi adicionada upstream no ncurses 6.5-20241228, que é mais recente. Por isso, apt install ncurses-term no Ubuntu 24.04 não pode produzir uma entrada xterm-ghostty, independentemente de quantas vezes for executado. tput -T <name> longname faz a verificação: imprime a descrição quando a entrada está presente e unknown terminal termina com o código de saída 3 quando ela não está.

Para instalar uma única entrada em todo o sistema, em vez do pacote completo, copie o código-fonte e compile-o como 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

O -t no segundo comando aloca um pseudo-terminal, para que sudo possa pedir a palavra-passe. Sem ele, o ssh não aloca um terminal para um comando remoto, e sudo termina com 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 precisa de uma palavra-passe. Esse erro é causado pela ausência do tty, não pelo terminfo.

Deixe o emulador fazer a transferência

Alguns emuladores incluem um auxiliar que aplica a correção 2 por si só. O kitty tem um ssh chamado kitten: kitten ssh myserver estabelece a ligação e copia automaticamente o terminfo do kitty para o host remoto. A documentação também apresenta a forma manual, infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin, com o til escapado pelo motivo descrito acima. O Ghostty documenta infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x - e, desde a versão 1.2.0, inclui funcionalidades de integração com a shell ativadas opcionalmente (ssh-env e ssh-terminfo) que automatizam ambas as correções. O Ghostty 1.4.0, lançado em October 27, 2026, adiciona um wrapper ghostty +ssh que não existe nas releases 1.3.x, e as duas funcionalidades opcionais passam a chamá-lo. Ele instala o terminfo incluído no Ghostty no host remoto antes de estabelecer a ligação e recorre a TERM=xterm-256color quando essa instalação falha, por exemplo, quando o servidor não tem tic. Na versão 1.4, ssh-env também deixa de substituir linhas SetEnv em ~/.ssh/config, pelo que uma substituição por host da correção 1 é respeitada.

Estes auxiliares executam os mesmos comandos que acabou de executar manualmente. A forma manual continua a ser importante, porque o auxiliar não consegue atuar quando a ligação começa noutro local, num jump host ou dentro de um script.

Quando o erro volta

Em sudo -i. Uma shell de login como root tem HOME=/root, e sudo mantém o seu TERM. O ncurses passa a procurar em /root/.terminfo, que não contém a sua entrada, e a falha volta a ocorrer apenas para root. Confirme com sudo -i env e leia as linhas HOME e TERM. Instale a entrada no diretório do sistema. Uma cópia em /root/.terminfo também pode funcionar, mas o ncurses pode limitar a procura no diretório pessoal para processos privilegiados. Por isso, execute tput longname como root para confirmar.

Dentro do tmux ou screen. Estes programas definem o seu próprio TERM para os programas executados dentro deles, normalmente screen-256color ou tmux-256color. Um servidor mais antigo conhece screen-256color e pode não conhecer tmux-256color. Assim, a shell exterior funciona, enquanto tudo dentro da sessão falha. A causa é a mesma, mas o nome é diferente. Execute tput -T tmux-256color longname no servidor para ver qual dos dois está disponível. Um ambiente de trabalho de terminal baseado em tmux oculta este problema até ao dia em que se liga a um host que ainda não corrigiu.

Num servidor novo. ~/.terminfo é específico de cada conta e de cada máquina. Por isso, uma VPS recriada começa novamente vazia.

O ecrã é apresentado, mas as teclas comportam-se de forma incorreta. Se o ecrã estiver correto, mas Home, End ou as teclas de função inserirem caracteres inesperados, o nome foi resolvido para uma entrada que não corresponde ao seu terminal. As sequências de teclas vêm da mesma entrada terminfo que as capacidades de apresentação. Por isso, uma entrada aproximada produz teclas aproximadas. Esse é o resultado habitual da correção 1 num emulador cujas sequências de teclas diferem de xterm. A correção 2 é a resposta mais limpa, porque a entrada real do seu emulador contém as sequências corretas para todos os programas ao mesmo tempo. Não é a única opção: a documentação do Vim indica que pode "alterar o código da tecla com o comando :set", e o Vim solicita diretamente os códigos de teclas a um xterm recente durante o arranque, em vez de depender apenas da entrada.

FAQ

Porque vejo apenas "unknown terminal type" por SSH?

Porque a base de dados que tem de conter a entrada do seu terminal é a do servidor. O emulador instala a descrição na máquina onde é executado, por isso os programas locais encontram-na sem qualquer intervenção. O SSH envia apenas o valor de TERM, porque o protocolo transporta esse nome no pedido de pseudo-terminal. O ncurses remoto procura o nome na base de dados remota e não encontra nada. Assim, initscr falha e o programa termina.

Posso corrigir isto sem ter root no servidor?

Sim, numa instalação padrão como a do Debian. O ncurses procura $HOME/.terminfo antes de qualquer diretório do sistema. Apenas uma variável $TERMINFO definida no servidor é consultada antes desse caminho. Portanto, em condições normais, basta colocar aí uma entrada para a sua conta. A pesquisa no diretório pessoal é opcional no ncurses. Por isso, a verificação de tput longname abaixo é importante. Execute infocmp -x | ssh user@host -- tic -x - uma vez por servidor. tic escreve no seu diretório pessoal quando não consegue escrever no caminho do sistema, que é o comportamento normal para uma conta sem privilégios. Inicie sessão e execute tput longname para confirmar que a pesquisa já resolve a entrada.

O que perco ao definir TERM=xterm-256color para um host?

Perde todas as capacidades descritas pelo seu emulador além da entrada xterm-256color, como a cor de 24 bits através de RGB e os sublinhados estilizados através de Smulx. Os programas que dependem da entrada terminfo não conseguem ver essas capacidades. Por isso, usam a alternativa mais próxima, a menos que sejam configurados de outra forma, como acontece com a opção termguicolors do Vim para a cor. As sequências das teclas de função também podem ser diferentes das do seu terminal real. Coloque a definição no cliente, em ~/.ssh/config, e não num .bashrc no servidor. Caso contrário, as sessões de terminais que já funcionavam também serão degradadas.

Porque é que o erro volta depois de sudo -i?

sudo -i inicia uma shell de login como root com HOME=/root, mantendo o valor de TERM. O ncurses passa então a procurar /root/.terminfo em vez do seu próprio diretório pessoal e não encontra nada. Por isso, root vê a mesma falha que já não ocorre na sua conta. Execute sudo -i env e verifique as linhas HOME e TERM. Compile a entrada no diretório do sistema com sudo tic -x -o /usr/share/terminfo. Uma cópia em /root/.terminfo também pode funcionar, mas o ncurses pode limitar a pesquisa no diretório pessoal para processos privilegiados. Por isso, confirme com tput longname como root.

apt install ncurses-term corrige sempre o problema?

Não. Apenas adiciona as entradas existentes na versão do ncurses incluída pela sua distribuição. O Ubuntu 24.04 inclui o ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.2, em novembro de 2026), e a entrada do Ghostty foi adicionada upstream no ncurses 6.5-20241228. Por isso, esse pacote não a pode conter. Verifique com tput -T <name> longname antes de depender do pacote e instale a entrada manualmente se a verificação continuar a indicar um terminal desconhecido.

Este artigo foi útil?

#terminfo#ssh#ncurses#tput#terminal