SSH unknown terminal type 오류 해결 방법

"unknown terminal type" 오류의 의미

SSH 연결 시 발생하는 "unknown terminal type" 오류는 TERM에 설정된 이름이 서버 측의 terminfo 데이터베이스에 존재하지 않음을 의미합니다. 터미널 에뮬레이터는 노트북에서 해당 이름을 설정하지만, 이를 인식해야 하는 데이터베이스는 원격 서버에 위치합니다. 조회에 실패하면 서버의 모든 curses 프로그램은 터미널의 기능을 설명하는 정보를 찾을 수 없으므로 화면을 그리기 전에 중단됩니다.

터미널 에뮬레이터의 모든 기능을 유지하면서 문제를 해결하는 방법은 간단합니다. 서버의 ~/.terminfo에 사용자 정의 terminfo 항목을 컴파일하여 추가하는 것입니다. ncurses는 시스템 디렉터리보다 홈 디렉터리를 먼저 검색하므로, root 권한이 필요 없으며 다른 사용자에게도 영향을 주지 않습니다.

TERM은 이름이며, terminfo는 데이터베이스입니다

TERM은 하나의 문자열을 담고 있으며, 그 문자열은 단지 키일 뿐입니다. terminfo는 터미널 설명이 컴파일된 데이터베이스이며, 프로그램은 이 키를 통해 올바른 설명을 찾습니다. 터미널 설명에는 터미널이 지원하는 색상 수, 커서를 12행 40열로 이동시키는 바이트 값, F5 키를 눌렀을 때 전송되는 바이트, 스타일이 적용된 밑줄을 그릴 수 있는지 여부 등이 기록됩니다. 리눅스에서 거의 모든 텍스트 사용자 인터페이스(TUI)를 구축하는 기반인 ncurses 라이브러리는 시작 시 이 설명을 읽어 들입니다. top, less, nano, watch과 같은 프로그램은 이 정보 없이는 화면을 단 한 줄도 그릴 수 없습니다.

본인의 항목을 확인해 보십시오:

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

tput longname은 TERM가 지정하는 항목에 대한 사람이 읽을 수 있는 설명을 출력합니다. xterm-256color에 대해 실행하면 다음과 같이 출력됩니다:

xterm with 256 colors

infocmp -1은 전체 항목을 디컴파일하여 기능별로 한 줄씩 출력합니다. 두 명령어가 모두 정상적으로 작동한다면, 이 기기의 데이터베이스는 현재 터미널을 인식하고 있는 것입니다. SSH 연결을 통해 접속한 원격지에서도 동일한 상태가 유지되어야 합니다.

SSH 접속 시에만 문제가 발생하는 이유

SSH는 터미널 이름만 전송하고 다른 정보는 보내지 않습니다. 클라이언트가 가상 터미널을 요청하면 TERM가 해당 요청과 함께 전달됩니다. OpenSSH 매뉴얼에는 "가상 터미널이 요청될 때마다 프로토콜에 필요하므로 TERM 환경 변수가 항상 전송된다"라고 명시되어 있습니다. 따라서 VPS의 로그인 셸은 사용 중인 에뮬레이터에 따라 TERM=xterm-ghostty이나 xterm-kitty 같은 이름을 받게 됩니다. 해당 이름에 대한 설명은 사용자의 노트북에 있는 데이터베이스에만 존재합니다. 사용 중인 에뮬레이터가 출시되기 전에 구축된 서버는 해당 이름을 알지 못합니다. SSH 연결 자체에는 터미널 설명 정보를 복사하는 기능이 없으며, 이는 의도된 설계입니다. 프로토콜은 기능 정보 전체가 아닌 이름만 전달하기 때문입니다.

존재하지 않는 이름을 사용하여 로컬 머신에서 동일한 오류를 재현할 수 있습니다.

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

tput: unknown terminal "xterm-nosuchthing"

종료 상태는 3이며, ncurses 문서에 따르면 이는 알 수 없는 터미널 유형이거나 데이터베이스가 누락되었음을 의미합니다. 모든 curses 프로그램은 동일한 조회 과정을 거치므로, 이름 하나가 누락되면 각 프로그램은 서로 다른 메시지를 출력하지만 그 근본 원인은 모두 동일합니다. nano은 Error opening terminal: xterm-nosuchthing.과 함께 중단되는데, 이는 시작 시 설명을 로드할 수 없을 때 발생하는 표준 ncurses 오류입니다. vim은 E558: Terminal entry not found in terminfo를 출력합니다. less은 WARNING: terminal is not fully functional을 출력합니다. 반쯤 작동하는 페이저와 시작을 거부하는 편집기는 서로 무관한 버그처럼 보이지만, 실제로는 동일한 파일 누락 문제입니다.

ncurses가 항목을 찾는 위치

ncurses는 terminfo(5)에 문서화된 고정 순서대로 검색을 수행합니다.

1. $TERMINFO이 설정되어 있다면 해당 디렉터리만 검색합니다.
2. $HOME/.terminfo.
3. $TERMINFO_DIRS에 나열된 모든 디렉터리.
4. 컴파일 시 지정된 위치. Debian 및 Ubuntu의 경우 /etc/terminfo, /lib/terminfo, /usr/share/terminfo이 포함됩니다.

위 경로를 무조건 신뢰하기보다 서버에서 infocmp -D를 실행하여 해당 ncurses 빌드가 사용하는 목록을 직접 확인하십시오. 2단계가 핵심입니다. 시스템 디렉터리보다 사용자 홈 디렉터리가 먼저 검색되므로, ~/.terminfo 아래에 파일을 하나 두는 것만으로 패키지 설치나 root 권한 없이도 계정의 조회 경로를 수정할 수 있습니다.

해결 방법 1: 서버가 이미 알고 있는 TERM 사용하기

가장 빠르게 문제를 해결하는 방법은 연결 시점에 다른 터미널 이름을 지정하는 것입니다.

TERM=xterm-256color ssh user@203.0.113.10

노트북의 ~/.ssh/config 파일에 해당 호스트에 대한 설정을 영구적으로 적용하십시오.

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

SetEnv는 클라이언트 측에서 2018년 8월에 출시된 OpenSSH 7.8 이상 버전을 사용해야 합니다. TERM은 서버의 허가가 필요 없는 유일한 변수입니다. 매뉴얼에 따르면 "SendEnv와 유사하지만 TERM 변수는 예외로, 서버가 환경 변수를 수락할 준비가 되어 있어야 합니다"라고 명시되어 있습니다. 따라서 이 방법은 AcceptEnv 설정이 전혀 없는 보안이 강화된 sshd 환경에서도 작동합니다.

이 방법의 제약 사항은 다음과 같습니다. 기본 xterm-256color를 넘어 에뮬레이터가 제공하는 모든 기능을 사용할 수 없게 됩니다. 여기에는 RGB 기능으로 광고되는 24비트 색상과 Smulx을 통한 스타일이 적용된 밑줄이 포함됩니다. 프로그램이 이러한 기능을 인식하지 못하므로 256색상과 일반 밑줄로 대체됩니다. 화면은 정상적으로 작동하지만, 선택한 터미널보다 기능이 제한될 뿐입니다.

서버의 .bashrc에 export TERM=xterm-256color을 추가하는 방식으로 문제를 해결하지 마십시오. 해당 파일은 서버가 이미 알고 있는 터미널 이름을 사용하는 연결을 포함하여 모든 연결에서 실행되므로, 정상적으로 작동하던 세션까지 성능을 저하시킵니다. 어떤 에뮬레이터를 실행 중인지 알고 있는 클라이언트 측에서 설정을 재정의하십시오.

해결 방법 2: terminfo 항목을 서버로 한 번 전송하기

이 방법은 에뮬레이터 설정을 그대로 유지하는 해결책입니다. 로컬에서 항목을 디컴파일한 뒤 SSH를 통해 파이프라인으로 전송하고, 원격지에서 다시 컴파일합니다.

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

infocmp -x은 현재 TERM에 대한 항목을 확장(사용자 정의) 기능을 포함하여 소스 텍스트로 출력합니다. tic -x는 해당 소스를 서버에서 다시 바이너리 설명 파일로 컴파일합니다. 양쪽 모두에서 -x을 사용하는 것이 중요한데, 이를 생략하면 Smulx와 같은 기능이 전송 과정에서 누락되어 자신의 터미널보다 하위 버전의 복사본이 생성되기 때문입니다.

tic는 가능할 경우 시스템 디렉터리에 기록하며, 사용자에게 쓰기 권한이 없을 때는 $HOME/.terminfo으로 대체합니다. VPS의 일반 계정은 홈 디렉터리를 사용하게 되는데, 이는 의도한 동작입니다. 다음과 같이 대상 경로를 지정할 수도 있습니다.

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

~/.terminfo 주위의 따옴표는 장식이 아닙니다. ssh은 명령어를 하나의 문자열로 결합하여 원격 셸에 전달하므로, 따옴표가 없는 ~는 로컬 셸에서 먼저 확장됩니다. 이 경우 계정명이 다를 수 있는 원격 장비로 리터럴 /home/yourname/.terminfo을 보내게 됩니다. tic은 권한 오류로 실패하거나, ncurses가 검색하지 않는 경로에 기록될 수 있습니다. 물결표(tilde)를 따옴표로 감싸야 원격 셸에서 올바르게 확장됩니다.

로그인 후 확인합니다.

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

tput longname가 터미널 설명을 출력한다면 조회가 성공한 것이며, ls은 터미널 이름의 첫 글자로 시작하는 하위 디렉터리에 컴파일된 파일이 있음을 보여줍니다. 그 후 top를 실행하거나 동일한 라이브러리를 통해 화면을 다시 그리는 watch -n1 uptime을 실행하여 실제 curses 프로그램이 화면을 정상적으로 그리는지 확인하십시오.

비용: 서버당 한 단계의 작업이 필요하며, 해당 항목은 특정 장비의 한 계정 홈 디렉터리에 저장됩니다. VPS를 재구축하면 항목은 사라집니다. 여러 서버를 동시에 프로비저닝하고 관리하는 도구에 이 명령어를 포함하면, 새로운 호스트가 생성될 때 항목이 이미 컴파일된 상태로 준비됩니다.

해결 방법 3: 확장 terminfo 데이터베이스 설치

root 권한이 있고 시스템의 모든 계정에서 해당 이름을 인식하게 하려면 다음을 수행합니다.

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

ncurses-term에는 기본 설치에서 제외된 터미널 설명이 포함되어 있습니다. 이 방법은 해결 방법 2와 달리 root를 포함한 모든 사용자의 터미널 이름을 수정합니다.

이 방법은 사용 중인 배포판의 ncurses 릴리스에 해당 터미널 항목이 포함되어 있을 때만 유효하므로, 무작정 실행하기 전에 확인이 필요합니다. Ubuntu 24.04는 (2026년 8월 기준) ncurses-bin 6.4+20240113-1ubuntu2.1을 제공합니다. Ghostty 항목은 ncurses 6.5-20241228 버전부터 업스트림에 추가되었는데, 이는 더 최신 버전이므로 Ubuntu 24.04의 apt install ncurses-term을 아무리 실행해도 xterm-ghostty 항목을 생성할 수 없습니다. tput -T <name> longname 명령으로 확인할 수 있습니다. 항목이 존재하면 설명을 출력하고, 존재하지 않으면 unknown terminal과 함께 종료 상태 3을 반환합니다.

패키지 전체를 설치하는 대신 단일 항목만 시스템 전체에 설치하려면, 소스 파일을 복사한 뒤 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은 의사 터미널(pseudo terminal)을 할당하여 sudo가 비밀번호를 입력받을 수 있게 합니다. 이 옵션이 없으면 sudo은 sudo: no tty present and no askpass program specified와 함께 종료될 수 있습니다.

에뮬레이터가 전송을 수행하도록 설정

일부 에뮬레이터는 2번 해결 방법을 자동으로 수행하는 도우미 기능을 제공합니다. kitty는 ssh kitten을 포함하고 있습니다. kitten ssh myserver은 원격 호스트에 연결하여 kitty의 terminfo를 자동으로 복사합니다. 해당 문서에서는 위에서 설명한 이유로 틸드(tilde)를 이스케이프 처리한 수동 방식인 infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin도 안내합니다. Ghostty는 infocmp -x xterm-ghostty | ssh YOUR-SERVER -- tic -x -을 문서화하고 있으며, 두 가지 해결 방법을 모두 자동화하는 셸 통합 기능(ssh-env 및 ssh-terminfo)과 +ssh 작업을 제공합니다.

이러한 도우미 기능은 방금 수동으로 실행한 것과 동일한 명령을 수행합니다. 점프 호스트나 스크립트 내부 등 연결이 다른 곳에서 시작되는 경우에는 도우미가 작동할 수 없으므로 수동 방식을 숙지하는 것이 여전히 중요합니다.

오류가 다시 발생할 때

sudo -i 환경에서. root 계정의 로그인 셸은 HOME=/root을 가지며, sudo는 사용자의 TERM를 유지합니다. ncurses는 이제 /root/.terminfo을 검색하는데, 여기에 해당 항목이 없으므로 root 계정에서만 오류가 반환됩니다. sudo -i env 명령으로 이를 확인하고 HOME 및 TERM 라인을 읽어 보십시오. 시스템 디렉터리에 해당 항목을 설치하거나 /root/.terminfo에 복사본을 배치하십시오.

tmux 또는 screen 내부에서. 이 프로그램들은 내부에서 실행되는 프로그램들을 위해 자체적인 TERM을 설정하며, 일반적으로 screen-256color 또는 tmux-256color을 사용합니다. 구형 서버는 screen-256color를 알고 있지만 tmux-256color를 인식하지 못할 수 있으므로, 외부 셸은 정상 작동하더라도 세션 내부의 모든 작업은 실패할 수 있습니다. 원인은 같지만 명칭이 다른 경우입니다. 서버에서 tput -T tmux-256color longname을 실행하여 두 가지 중 무엇을 사용하는지 확인하십시오. tmux 기반의 터미널 작업 환경은 아직 수정하지 않은 호스트에 접속할 때까지 이 문제를 숨길 수 있습니다.

새 서버에서. ~/.terminfo은 계정별 및 머신별로 설정되므로, 재구축된 VPS는 다시 비어 있는 상태로 시작됩니다.

화면은 그려지지만 키 입력이 잘못될 때. 화면 표시는 정상인데 Home, End 또는 기능 키를 눌렀을 때 엉뚱한 문자가 입력된다면, 터미널과 일치하지 않는 항목으로 이름이 해석된 것입니다. 키 시퀀스는 화면 그리기 기능과 동일한 terminfo 항목에서 가져오므로, 근사치 항목을 사용하면 키 입력도 근사치로 작동합니다. 이는 xterm과 키 시퀀스가 다른 에뮬레이터에서 첫 번째 해결책을 적용했을 때 흔히 발생하는 결과입니다. 에뮬레이터의 실제 항목만이 올바른 시퀀스를 포함하고 있으므로, 두 번째 해결책이 정답입니다.

FAQ

Why do I only see "unknown terminal type" over SSH?

Because the database that has to hold your terminal's entry is the one on the server. Your emulator installs its description on the machine it runs on, so local programs find it without any effort from you. SSH sends only the value of TERM, since the protocol carries that name with the pseudo-terminal request. The remote ncurses looks the name up in the remote database and finds nothing, so initscr fails and the program stops.

Can I fix this without root on the server?

Yes. ncurses searches $HOME/.terminfo before any system directory, so an entry there is enough for your account. Run infocmp -x | ssh user@host -- tic -x - once per server. tic writes into your home directory when it cannot write to the system path, which is the normal case for an unprivileged account. Log in and run tput longname to confirm the lookup now resolves.

What do I lose by setting TERM=xterm-256color for a host?

Every capability your emulator describes beyond the xterm-256color entry, such as 24-bit colour through RGB and styled underlines through Smulx. Programs cannot see those capabilities, so they use the closest fallback. Function-key sequences may also differ from your real terminal. Put the setting on the client in ~/.ssh/config rather than in a .bashrc on the server, which would downgrade sessions from terminals that already worked.

Why does the error come back after sudo -i?

sudo -i starts a login shell as root with HOME=/root, while keeping your TERM value. ncurses then searches /root/.terminfo instead of your own home directory and finds nothing, so root sees the same failure your account no longer sees. Run sudo -i env and check the HOME and TERM lines. Compile the entry into the system directory with sudo tic -x -o /usr/share/terminfo, or copy it into /root/.terminfo.

Does apt install ncurses-term always fix it?

No. It adds only the entries that existed in the ncurses release your distribution packaged. Ubuntu 24.04 ships ncurses 6.4 (ncurses-bin 6.4+20240113-1ubuntu2.1, as of August 2026), and Ghostty's entry was added upstream in ncurses 6.5-20241228, so that package cannot contain it. Check with tput -T <name> longname before relying on the package, and ship the entry yourself when the check still reports an unknown terminal.