VS Code Remote-SSH 연결 실패, 원인 6가지 5분 진단 가이드

SSH 로그인은 되는데 VS Code만 멈춘다 — '연결 실패'는 한 가지 문제가 아니다

터미널에서 ssh user@host는 멀쩡히 붙는데, VS Code Remote-SSH 창만 무한 로딩에 빠지거나 Could not establish connection to <host> 메시지를 띄우며 재시도 루프에 갇힌 적 있으신가요? 이 상황의 핵심은 인증은 이미 통과했다는 것입니다. 즉 publickey 문제가 아니라, SSH 접속 직후 VS Code가 원격 서버에 ~/.vscode-server를 설치·기동하는 별개 레이어에서 깨지고 있다는 뜻이죠.

📌 이 글은 SSH 인증(키, authorized_keys, Permission denied (publickey)) 문제는 다루지 않습니다. 그 부분은 별도 발행한 'Git/SSH Permission denied (publickey) 해결' 글을 참고하세요. 본 글은 인증 통과 후 원격 확장 서버(VS Code Server) 기동 단계 문제만 다룹니다.

요즘은 EC2·VPS·사내 리눅스, Codespaces·DevPod 같은 클라우드 원격 개발이 보편화되면서 이 기동 단계 이슈가 부쩍 늘었습니다. Cursor 같은 VS Code 포크도 동일한 Remote-SSH 메커니즘을 쓰기 때문에 증상과 해법이 같습니다.

먼저 로그를 여는 법부터 익혀둡시다. 어디서 깨지는지 보이지 않으면 5분 진단이 불가능합니다.

• 출력 패널 열기: Ctrl/Cmd+Shift+U → 우측 상단 드롭다운에서 Remote-SSH 채널 선택
• 개발자 도구: 명령 팔레트(Ctrl/Cmd+Shift+P) → Developer: Toggle Developer Tools
• 원격 서버에 직접 SSH로 붙어 로그 확인:

df -h ~
ls -la ~/.vscode-server
tail -n 50 ~/.vscode-server/.*.log

이 세 줄이 모든 진단의 출발점입니다.

에러 원문으로 원인 빠르게 좁히기: 메시지별 분기표

같은 "연결 실패"라도 VS Code가 뱉는 문구에 따라 의심할 원인이 다릅니다.

공통 1차 진단은 위에서 본 df -h ~, ls -la ~/.vscode-server, tail 세트입니다. 이걸 먼저 돌리고 아래 6분기로 들어가세요.

원인별 5분 진단·해결 (6분기)

(1) 디스크 부족으로 server 설치 실패

증상은 로그에 No space left on device, 그리고 The VS Code Server failed to start. 원격 홈 파티션이 꽉 차면 설치가 통째로 실패합니다.

# 진단
df -h ~
du -sh ~/.vscode-server
du -sh ~/.cache ~/.local 2>/dev/null

# 해결: 캐시·로그 정리로 공간 확보
rm -rf ~/.vscode-server/data/logs/*
rm -rf ~/.cache/*
# 그래도 부족하면 큰 파일 탐색
du -ah ~ | sort -rh | head -20

홈 파티션 자체가 작다면 인프라 담당에게 볼륨 증설을 요청하세요.

(2) SSH config / ProxyJump·점프호스트 오류

사내 보안 점프호스트를 거치는 환경에서 자주 터집니다. 터미널 ssh는 OS 기본 config를 잘 읽지만, VS Code가 같은 설정을 다르게 해석해 핸드셰이크가 깨지기도 합니다.

# 진단: verbose로 어디서 끊기는지 확인
ssh -v user@host

~/.ssh/config에 멀티홉을 명시적으로 적어주는 게 가장 안전합니다.

Host bastion
    HostName bastion.example.com
    User devops
    IdentityFile ~/.ssh/id_ed25519

Host target
    HostName 10.0.1.20
    User myuser
    ProxyJump bastion
    IdentityFile ~/.ssh/id_ed25519

이후 VS Code에서는 target 호스트로 접속합니다. 그래도 안 되면 설정에서 remote.SSH.useLocalServer를 토글해 보세요(아래 4장 참고).

(3) glibc/구버전 OS 미지원으로 server 바이너리 미실행

CentOS 7, Ubuntu 16.04 같은 EOL LTS 서버에서 폭증하는 이슈입니다. 증상은 GLIBC_2.x not found와 server 프로세스 즉시 종료.

# 진단
ldd --version
cat /etc/os-release

최신 VS Code Server는 비교적 높은 glibc를 요구합니다. 해결 분기는 세 갈래입니다.

1. 호환 VS Code 버전 핀: 해당 OS를 지원하던 구버전 VS Code(예: 1.85 이전)로 다운그레이드 후 자동 업데이트를 끕니다.
2. 레거시 서버 옵션 사용: VS Code가 제공하는 레거시 빌드 지원이 있는 버전을 사용.
3. OS 업그레이드: 가능하면 glibc 2.28+ 환경(예: Ubuntu 20.04+, Rocky 8+)으로 이전하는 게 근본 해결입니다.

(4) ~/.vscode-server 손상 → 삭제 후 재설치

설치가 중간에 끊겼거나 디스크가 찼다 풀린 뒤 흔히 남는 상태입니다. Failed to connect to the remote extension host server가 대표 증상입니다.

# 원격 서버에서 직접 삭제
rm -rf ~/.vscode-server

VS Code 안에서 더 깔끔하게 하려면 명령 팔레트(Ctrl/Cmd+Shift+P) → Remote-SSH: Kill VS Code Server on Host 를 실행한 뒤 재접속하세요. 다시 붙으면 서버가 자동으로 새로 설치됩니다.

(5) 방화벽 / 셸 RC(.bashrc) 비정상 출력으로 핸드셰이크 실패

의외로 흔한 함정입니다. VS Code는 비대화형 셸로 명령을 실행하는데, .bashrc나 .profile에서 echo, 배너, figlet, 회사 보안 안내 메시지 같은 걸 출력하면 핸드셰이크 데이터가 오염돼 Could not establish connection to가 뜹니다.

# 진단: 출력이 깨끗한지 확인 — OK 외 다른 텍스트가 섞이면 범인
ssh user@host 'echo OK'

해결은 .bashrc 맨 위에 비대화형 분기를 넣는 것입니다.

# 대화형 셸이 아니면 즉시 종료 (이 줄 위로 출력 코드를 두지 말 것)
[[ $- == *i* ]] || return

추가로 outbound 방화벽이 VS Code의 다운로드 서버 접근을 막는지도 확인하세요(폐쇄망이면 오프라인 설치가 필요).

(6) 권한 / 홈 디렉터리 quota

홈 디렉터리 소유권이 root로 바뀌었거나 디스크 quota를 초과하면 server가 파일을 못 씁니다.

# 진단
ls -la ~
quota -s
touch ~/.vscode-server/test && echo "쓰기 가능" || echo "쓰기 불가"

# 해결: 소유권·권한 복구 (myuser는 본인 계정으로)
sudo chown -R myuser:myuser ~/.vscode-server
chmod -R u+rwX ~/.vscode-server

quota 초과라면 시스템 관리자에게 상향을 요청해야 합니다. touch 한 줄이 "쓰기 가능 여부"를 가장 빠르게 가려줍니다.

💬 실무 경험담: 제가 가장 많이 만난 범인은 의외로 (5)번 .bashrc 출력 오염이었습니다. 신규 입사자 온보딩용으로 로그인 배너를 .bashrc에 넣는 회사가 많은데, 터미널에선 멀쩡해도 Remote-SSH만 골라서 깨집니다. ssh user@host 'echo OK' 한 방이면 5초 만에 잡힙니다. 그래서 저는 무한 로딩이 뜨면 디스크보다 이 명령을 먼저 칩니다.

그래도 안 될 때: VS Code 쪽 설정·캐시 리셋과 토글 모음

원격 서버가 멀쩡한데도 클라이언트가 재시도 루프에 빠진다면, VS Code 설정을 손볼 차례입니다.

• Remote-SSH: Kill VS Code Server on Host: 명령 팔레트에서 실행해 서버 프로세스를 죽이고 재설치 유도(4장).
• 로컬 ~/.vscode/extensions 충돌이 의심되면 문제 확장을 비활성화한 뒤 재접속.

주요 설정값(settings.json):

무한 로딩 시 재시도 루프 끊는 순서: ① 창 우하단 연결 상태 클릭 → Close Remote Connection ② Kill VS Code Server on Host ③ 원격에서 rm -rf ~/.vscode-server ④ showLoginTerminal 켜고 재접속해 실제 오류 확인.

결론: 5분 진단 체크리스트

다음에 또 막히면 위에서부터 순서대로 따라가세요.

이 표만 책상에 붙여둬도 다음 장애 때 당황하지 않습니다.

자주 묻는 질문 (FAQ)

Q. ssh는 되는데 VS Code만 무한 로딩이에요. A. 인증은 통과한 상태이고 ~/.vscode-server 기동 단계에서 막힌 겁니다. 먼저 df -h ~(디스크)와 ssh user@host 'echo OK'(.bashrc 오염)를 확인하세요. 둘 중 하나가 대부분의 원인입니다.

Q. .vscode-server를 지워도 되나요? A. 네, 안전합니다. 캐시·서버 바이너리·설치한 원격 확장이 들어있을 뿐, 코드/데이터에는 영향 없습니다. rm -rf ~/.vscode-server 후 재접속하면 자동 재설치됩니다.

Q. 회사 점프호스트를 거쳐야 하는데 설정은 어떻게 하나요? A. ~/.ssh/config에 ProxyJump bastion을 명시한 Host 블록을 만들고 그 호스트로 접속하세요(2장 예시). 안 되면 remote.SSH.useLocalServer를 false로 토글해 보세요.

Q. 구버전 CentOS/Ubuntu라 GLIBC_2.x not found가 나요. A. ldd --version으로 glibc 버전을 확인하세요. 최신 VS Code Server가 요구하는 버전보다 낮으면, 호환되는 구버전 VS Code로 핀 고정하거나 OS를 glibc 2.28+ 환경으로 업그레이드해야 합니다.

Q. 권한 에러로 설치가 막혀요. A. touch ~/.vscode-server/test로 쓰기 가능 여부를 확인하고, 소유권이 깨졌다면 sudo chown -R 계정:계정 ~/.vscode-server로 복구하세요. quota 초과면 관리자에게 상향을 요청해야 합니다.