SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

SSH 접속 시 unknown terminal type 오류 해결 방법

SSH 접속 중 발생하는 unknown terminal type 오류는 원격 서버에 TERM 정보가 없을 때 발생합니다. 루트 권한 없이 홈 디렉터리에 terminfo를 컴파일하여 curses 프로그램 실행 문제를 해결하는 구체적인 방법을 안내합니다.

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

"unknown terminal type" 오류의 의미

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

터미널 에뮬레이터의 모든 기능을 유지하면서 문제를 해결하는 방법은 한 가지 명령어를 사용하는 것입니다. 서버의 ~/.terminfo에 사용자 정의 terminfo 항목을 컴파일하여 추가하면 됩니다. Debian과 같은 표준 빌드 환경에서 ncurses는 시스템 디렉터리보다 먼저 홈 디렉터리를 검색합니다($TERMINFO 변수가 설정된 경우에만 해당 변수를 가장 먼저 확인합니다). 따라서 이 작업은 root 권한이 필요 없으며 다른 사용자에게도 영향을 주지 않습니다. ncurses에서 홈 디렉터리 조회는 선택 사항이므로, 수정 후 확인 절차가 중요합니다.

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은 항목을 디컴파일하여 기능별로 한 줄씩 출력합니다. -x 옵션을 추가하지 않으면 확장(사용자 정의) 기능은 생략됩니다. infocmp -1 -x와 같이 사용하십시오. 두 명령어가 모두 정상적으로 작동한다면, 이 기기의 데이터베이스는 해당 터미널을 인식하고 있는 것입니다. 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이며, tput 매뉴얼에는 이를 "인식할 수 없는 터미널 유형(unrecognized terminal type)"으로 정의하고 있습니다. 모든 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단계가 핵심입니다. Debian의 ncurses 빌드는 이 기능을 비활성화하지 않으며, 해당 기능이 존재할 경우 시스템 디렉터리보다 사용자의 홈 디렉터리를 먼저 탐색합니다. 따라서 ~/.terminfo 아래에 파일을 하나 생성하면 패키지 설치나 root 권한 없이도 해당 계정의 조회 경로를 수정할 수 있습니다. 수정 후 tput longname을 실행하면 서버의 빌드가 해당 설정을 반영하는지 확인할 수 있습니다. 유일한 예외는 1단계입니다. 서버에서 echo "$TERMINFO"을 실행했을 때 결과가 출력된다면 해당 위치가 가장 먼저 확인되며, 그곳에 동일한 이름의 항목이 있을 경우 사용자의 설정보다 우선합니다.

해결 방법 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

TERM를 재정의하기 위해 SetEnv을 사용하는 방식은 클라이언트 측에 2021년 8월에 출시된 OpenSSH 8.7 이상 버전이 필요합니다. 이전 버전의 클라이언트는 이 설정과 관계없이 사용 중인 에뮬레이터의 TERM을 그대로 전송합니다. TERM는 서버의 허용 설정이 필요 없는 유일한 변수입니다. 매뉴얼에 따르면 "SendEnv와 유사하지만 TERM 변수는 예외적으로 서버가 환경 변수를 수락할 준비가 되어 있어야 한다"고 명시되어 있습니다. 따라서 이 방법은 AcceptEnv 설정이 전혀 없는 보안이 강화된 sshd 환경에서도 작동합니다.

감수해야 할 점: 일반 xterm-256color을 제외하고 에뮬레이터가 제공하는 모든 기능이 제한됩니다. 여기에는 RGB 기능을 통해 광고되는 24비트 컬러와 Smulx을 통한 스타일 밑줄이 포함됩니다. terminfo 항목에 의존하는 프로그램은 해당 기능을 인식할 수 없게 되므로, 별도로 시퀀스를 전송하도록 설정하지 않는 한 256 컬러와 일반 밑줄로 대체됩니다. 예를 들어 Vim은 내장된 t_8f 및 t_8b 시퀀스가 대부분의 터미널에서 작동하기 때문에 set termguicolors를 사용하여 24비트 컬러를 여전히 표현할 수 있습니다. 화면은 정상적으로 출력되지만, 선택한 터미널보다 기능이 제한된 상태로 동작하게 됩니다.

서버의 .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년 11월 기준) ncurses-bin 6.4+20240113-1ubuntu2.2을 제공합니다. Ghostty 항목은 ncurses 6.5-20241228 버전부터 업스트림에 추가되었는데, 이는 더 최신 버전이므로 Ubuntu 24.04에서 apt install ncurses-term을 아무리 실행해도 xterm-ghostty 항목을 생성할 수 없습니다. tput -T <name> longname 명령으로 확인이 가능합니다. 항목이 존재하면 설명을 출력하고, 존재하지 않으면 종료 상태 3과 함께 unknown terminal를 반환합니다.

패키지 전체를 설치하는 대신 단일 항목만 시스템 전체에 적용하려면, 소스를 복사한 뒤 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이 비밀번호를 입력받을 수 있게 합니다. 이 옵션이 없으면 ssh는 원격 명령을 위해 터미널을 할당하지 않으며, 비밀번호가 필요할 때 sudo은 sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper 오류를 내며 중단됩니다. 해당 오류는 terminfo가 아닌 tty 부재와 관련된 것입니다.

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

일부 에뮬레이터는 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 -를 문서화하고 있으며, 1.2.0 버전부터는 두 가지 해결책을 자동화하는 선택적 셸 통합 기능(ssh-env 및 ssh-terminfo)을 제공합니다. 2026년 10월 27일에 출시된 Ghostty 1.4.0 버전은 1.3.x 릴리스에는 없는 ghostty +ssh 래퍼를 추가했으며, 두 가지 선택적 기능은 이제 이 래퍼를 호출합니다. 이 래퍼는 연결 전 원격 호스트에 Ghostty의 번들 terminfo를 설치하며, 서버에 tic이 없는 경우와 같이 설치에 실패하면 TERM=xterm-256color으로 대체합니다. 1.4 버전부터 ssh-env은 ~/.ssh/config 내의 SetEnv 라인을 덮어쓰지 않으므로, 1번 해결책에서 설정한 호스트별 오버라이드 설정이 유지됩니다.

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

오류가 다시 발생할 때

sudo -i 하위. root 계정의 로그인 셸은 HOME=/root를 가지며, sudo은 사용자의 TERM를 유지합니다. 이제 ncurses는 /root/.terminfo를 검색하는데, 여기에 해당 항목이 없으므로 root 계정에서만 오류가 반환됩니다. sudo -i env으로 확인하고 HOME 및 TERM 라인을 읽어 보십시오. 시스템 디렉터리에 해당 항목을 설치하십시오. /root/.terminfo에 복사본을 두는 방법도 가능하지만, ncurses가 권한 있는 프로세스에 대해서는 홈 디렉터리 조회를 제한할 수 있으므로 root 권한으로 tput longname을 실행하여 확인하십시오.

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

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

화면은 그려지지만 키가 오작동할 때. 화면 표시는 정상인데 Home, End 또는 기능 키가 엉뚱한 문자를 입력한다면, 터미널과 일치하지 않는 항목으로 이름이 해석된 것입니다. 키 시퀀스는 화면 그리기 기능과 동일한 terminfo 항목에서 가져오므로, 근사치 항목은 근사치 키를 제공합니다. 이는 키 시퀀스가 xterm과 다른 에뮬레이터에서 1번 해결책을 적용했을 때 흔히 발생하는 결과입니다. 2번 해결책이 가장 깔끔한 방법인데, 에뮬레이터의 실제 항목이 모든 프로그램에 대해 즉시 올바른 시퀀스를 전달하기 때문입니다. 이것이 유일한 방법은 아닙니다. Vim 설명서에 따르면 ":set 명령으로 키 코드를 변경"할 수 있으며, Vim은 항목에만 의존하는 대신 시작 시 최신 xterm에 키 코드를 직접 질의하기도 합니다.

FAQ

SSH 접속 시 "unknown terminal type" 오류가 발생하는 이유는 무엇입니까?

터미널 정보를 담고 있는 데이터베이스가 서버에 존재해야 하기 때문입니다. 터미널 에뮬레이터는 자신이 실행되는 로컬 시스템에 터미널 정의를 설치하므로 로컬 프로그램은 별도의 설정 없이 이를 인식합니다. SSH는 프로토콜을 통해 의사 터미널(pseudo-terminal) 요청과 함께 TERM 값만 전달합니다. 원격지의 ncurses가 해당 이름을 데이터베이스에서 찾지 못하면 initscr이 실패하고 프로그램이 중단됩니다.

서버의 root 권한 없이 이 문제를 해결할 수 있습니까?

네, Debian과 같은 표준 빌드 환경에서는 가능합니다. ncurses는 시스템 디렉터리보다 $HOME/.terminfo을 먼저 탐색합니다. 서버에 $TERMINFO 변수가 설정되어 있지 않다면, 해당 경로에 터미널 정의를 추가하는 것만으로도 계정 수준에서 충분히 해결됩니다. ncurses에서 홈 디렉터리 탐색은 선택 사항이므로 아래의 tput longname 확인 과정이 중요합니다. 서버마다 한 번씩 infocmp -x | ssh user@host -- tic -x -를 실행하십시오. tic는 시스템 경로에 쓰기 권한이 없는 일반 계정의 경우 홈 디렉터리에 터미널 정의를 기록합니다. 다시 로그인한 뒤 tput longname을 실행하여 조회가 정상적으로 이루어지는지 확인하십시오.

특정 호스트에 TERM=xterm-256color을 설정하면 어떤 기능을 잃게 됩니까?

xterm-256color 항목을 넘어선 에뮬레이터의 모든 확장 기능을 잃게 됩니다. 예를 들어 RGB를 통한 24비트 컬러나 Smulx을 통한 스타일 밑줄 등이 포함됩니다. terminfo 항목에 의존하는 프로그램은 이러한 기능을 인식하지 못하므로, Vim의 termguicolors 옵션처럼 별도로 설정하지 않는 한 가장 유사한 대체 기능을 사용하게 됩니다. 기능 키 시퀀스 또한 실제 터미널과 다를 수 있습니다. 이 설정은 서버의 .bashrc에 적용하여 기존에 잘 작동하던 터미널 세션까지 저하시키기보다는, 클라이언트의 ~/.ssh/config에 적용하는 것이 좋습니다.

sudo -i를 실행했는데도 왜 오류가 다시 발생합니까?

sudo -i는 TERM 값을 유지한 채 HOME=/root을 사용하여 root 권한으로 로그인 셸을 시작합니다. 이때 ncurses는 사용자의 홈 디렉터리가 아닌 /root/.terminfo을 탐색하는데, 이곳에는 정보가 없으므로 root 계정에서는 다시 오류가 발생합니다. sudo -i env를 실행하여 HOME 및 TERM 라인을 확인하십시오. sudo tic -x -o /usr/share/terminfo를 사용하여 시스템 디렉터리에 해당 항목을 컴파일하십시오. /root/.terminfo에 복사본을 두는 방법도 있지만, ncurses는 권한이 있는 프로세스에 대해 홈 디렉터리 탐색을 제한할 수 있으므로 root 권한으로 tput longname를 통해 확인해야 합니다.

apt install ncurses-term를 실행하면 항상 문제가 해결됩니까?

아닙니다. 이 명령은 배포판 패키지에 포함된 ncurses 릴리스에 존재하는 항목만 추가합니다. Ubuntu 24.04는 ncurses 6.4(2026년 11월 기준 ncurses-bin 6.4+20240113-1ubuntu2.2)를 제공하는데, Ghostty 항목은 ncurses 6.5-20241228 버전에서 업스트림에 추가되었으므로 해당 패키지에는 포함될 수 없습니다. 패키지에 의존하기 전에 tput -T <name> longname로 확인하고, 여전히 알 수 없는 터미널로 보고된다면 직접 항목을 추가하십시오.

이 글이 도움이 되었나요?

#terminfo#ssh#ncurses#tput#terminal