VS Code Remote-SSH 연결 오류 terminalRemoteResolver 해결법

by

VS Code Remote-SSH, 갑자기 연결이 안 될 때

원격 서버에 매일 잘 붙던 VS Code가 어느 날 갑자기 연결을 거부한다면 당황스럽습니다. 특히 오류 메시지에 terminalRemoteResolver처럼 낯선 API 이름이 등장하면 더욱 그렇습니다. 결론부터 말하면, 이 오류는 대부분 로컬 VS Code 본체와 Remote-SSH 확장 프로그램의 버전이 서로 어긋났을 때 발생합니다. 이 글에서는 오류의 정확한 원인과, 실제로 효과가 있었던 해결 순서를 단계별로 정리했습니다.

어떤 오류 메시지가 뜨는가

원격 개발 환경을 구축해 사용하다 보면 종종 아래와 같은 팝업을 마주하게 됩니다.

Could not establish connection to “서버 주소”: Extension ‘ms-vscode-remote.remote-ssh’ CANNOT use API proposal: terminalRemoteResolver.

메시지를 조금 더 읽어보면, 확장 프로그램의 package.json에 선언된 enabledApiProposals 목록에 resolvers, tunnels, terminalDataWriteEvent 등은 있지만 정작 필요한 terminalRemoteResolver는 빠져 있다는 내용이 이어집니다. 즉 VS Code 본체가 요구하는 API 스펙과 확장이 실제로 지원하는 API 스펙 사이에 간극이 생긴 상태입니다.

이런 유형의 오류는 원격 서버(Lightsail, EC2 등 어떤 클라우드 인스턴스든 무관)에 SSH로 접속해 헤드리스 개발 도구를 상시 실행해 두는 워크플로우를 쓰는 경우 특히 자주 겪게 됩니다. 서버 자체는 멀쩡한데 로컬 클라이언트 쪽 문제로 접속 자체가 막히는 상황이라 처음엔 원인 파악이 까다롭습니다.

왜 이런 오류가 발생하는가

VS Code는 버전이 올라갈 때마다 내부적으로 사용하는 “Proposed API” 목록을 갱신합니다. Remote-SSH 확장 프로그램도 이 목록에 맞춰 자신의 package.json을 함께 업데이트해야 하는데, 아래와 같은 상황에서 둘 사이 싱크가 어긋납니다.

  • 로컬 VS Code만 자동 업데이트되고 확장 프로그램은 구버전 캐시로 남아있는 경우
  • 반대로 확장은 최신인데 VS Code 본체가 구버전인 경우
  • Insiders 빌드와 Stable 빌드를 혼용하면서 서로 다른 채널의 확장이 섞여 설치된 경우
  • 원격 서버 쪽에 남아있는 .vscode-server 캐시가 새 버전과 호환되지 않는 경우

즉 로컬 설정, 원격 서버 캐시 양쪽 모두 의심해봐야 하는 문제입니다.

해결 순서 1: 로컬 VS Code 버전부터 확인

가장 먼저 할 일은 VS Code 본체가 최신 버전인지 확인하는 것입니다. 메뉴에서 Help > Check for Updates를 실행하면 됩니다. Remote-SSH 확장은 항상 최신 Stable VS Code와 짝을 맞춰 테스트되기 때문에, 본체가 구버전이면 이런 API 불일치가 쉽게 발생합니다.

해결 순서 2: Remote-SSH 확장 재설치

버전이 최신인데도 같은 오류가 난다면 확장 프로그램 자체의 설치 상태를 의심해볼 차례입니다.

  1. 확장(Extensions) 탭에서 Remote - SSH 검색
  2. 톱니바퀴 아이콘 클릭 후 Uninstall
  3. VS Code 완전히 재시작
  4. 다시 검색해 설치

캐시가 꼬여 있던 경우 이 단계에서 해결되는 경우가 많습니다.

해결 순서 3: 원격 서버의 VS Code Server 캐시 삭제

실제로 가장 확실하게 문제를 해결하는 방법은 원격 서버 쪽에 남아있는 캐시를 지우는 것입니다. 로컬에서 별도 터미널로 원격 서버에 SSH 접속한 뒤 아래 명령을 실행합니다.

rm -rf ~/.vscode-server

이 디렉토리를 지우면 다음 Remote-SSH 연결 시 서버 쪽 구성요소가 처음부터 새로 설치됩니다. 로컬과 원격 양쪽의 버전 정보가 완전히 새로 맞춰지기 때문에, 위 두 단계로도 해결되지 않던 문제가 여기서 풀리는 경우가 많습니다.

해결 순서 4: Insiders / Stable 버전 혼용 여부 점검

VS Code Insiders를 사용 중인데 설치된 Remote-SSH 확장은 Stable 채널용이거나, 혹은 그 반대인 경우에도 동일한 오류가 발생합니다. 터미널에서 아래 명령으로 현재 버전과 채널을 확인할 수 있습니다.

code --version

Insiders와 Stable을 오가며 작업하는 환경이라면, 두 채널의 확장 설치 상태가 서로 꼬여 있지 않은지 별도로 점검해볼 필요가 있습니다.

해결 순서 5: 그래도 안 될 때 — 원격 서버 프로세스 강제 종료

위 방법들로도 해결되지 않는다면, 명령 팔레트(Ctrl+Shift+P 또는 Cmd+Shift+P)에서 Remote-SSH: Kill VS Code Server on Host...를 실행합니다. 이 명령은 원격 서버에서 돌고 있는 VS Code Server 프로세스를 강제로 종료시키는데, 캐시 삭제만으로는 정리되지 않던 좀비 프로세스가 남아있던 경우 이 단계에서 마무리됩니다. 실행 후 다시 연결을 시도하면 됩니다.

자주 묻는 질문

Q. 서버는 재부팅했는데도 오류가 계속됩니다.
서버 재부팅은 .vscode-server 캐시나 로컬 확장 버전 불일치를 해결해주지 않습니다. 이 오류는 클라이언트(로컬 VS Code)와 확장 프로그램 버전 문제이므로, 서버 재부팅보다는 위 1~3번 순서를 먼저 시도하는 편이 효율적입니다.

Q. 같은 오류가 다른 확장에서도 발생할 수 있나요?
네. terminalRemoteResolver 외에도 다른 Proposed API 이름으로 동일한 유형의 오류가 발생할 수 있습니다. 원인 구조는 동일하므로 위 해결 순서를 그대로 적용하면 됩니다.

Q. 원격 서버에서 헤드리스로 CLI 도구를 상시 실행 중인데, 캐시를 지우면 그 프로세스도 영향을 받나요?
~/.vscode-server 삭제는 VS Code 자체의 원격 구성요소만 초기화할 뿐, tmux나 별도 세션으로 띄워둔 다른 백그라운드 프로세스에는 영향을 주지 않습니다. 다만 안전하게 진행하려면 삭제 전 해당 프로세스들이 VS Code Server에 종속되어 있지 않은지 한 번 확인하는 것이 좋습니다.

마무리

정리하면, VS Code Remote-SSH의 terminalRemoteResolver 오류는 로컬 VS Code와 확장 버전 불일치, 원격 서버의 캐시 잔존, Insiders/Stable 혼용이라는 세 가지 원인 중 하나일 가능성이 높습니다. 로컬 업데이트 확인 → 확장 재설치 → 원격 서버 캐시 삭제 순으로 시도하면 대부분의 경우 해결됩니다. 원격 개발 환경을 상시 운영하는 경우라면 이런 버전 불일치는 주기적으로 재발할 수 있으므로, 오류 메시지에 등장하는 API 이름을 기억해두면 다음번에는 훨씬 빠르게 원인을 좁힐 수 있습니다.

Leave a Comment