VS Code Remote-SSH Connection Failures: A 5-Minute Diagnostic Guide to 6 Common Causes

VS Code Remote-SSH Connection Failures: A 5-Minute Diagnostic Guide to 6 Common Causes

SSH login works, but VS Code hangs — “connection failed” is not a single problem

Have you ever had ssh user@host connect just fine from a terminal, while the VS Code Remote-SSH window sits in infinite loading or loops on Could not establish connection to <host>? The key point is that authentication already succeeded. This is not a publickey issue. After SSH connects, VS Code installs and starts ~/.vscode-server on the remote host, and that separate layer is what is breaking.

📌 This post does not cover SSH authentication (keys, authorized_keys, Permission denied (publickey)). See the separately published “Fixing Git/SSH Permission denied (publickey)” article for that. This post covers only problems in the remote extension server (VS Code Server) startup stage after authentication succeeds.

As remote development on EC2, VPS, internal Linux, Codespaces, DevPod, and similar setups has become common, this startup-stage issue has become much more frequent. VS Code forks such as Cursor use the same Remote-SSH mechanism, so the symptoms and fixes are the same.

First, learn how to open the logs. You cannot diagnose anything in five minutes if you cannot see where it breaks.

• Open the Output panel: Ctrl/Cmd+Shift+U → in the top-right dropdown, select the Remote-SSH channel
• Developer tools: Command Palette (Ctrl/Cmd+Shift+P) → Developer: Toggle Developer Tools
• SSH directly to the remote server and inspect logs:

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

These three lines are the starting point for every diagnosis.

Narrow the cause from the raw error: a message-by-message branch table

Even with the same “connection failed” outcome, the phrase VS Code prints points to different likely causes.

The shared first-pass diagnosis is the df -h ~, ls -la ~/.vscode-server, and tail set above. Run that first, then follow the six branches below.

5-minute diagnosis and fix by cause (6 branches)

(1) Server install fails because the disk is full

Symptoms: No space left on device in the logs, plus The VS Code Server failed to start. If the remote home partition is full, the install fails entirely.

# 진단
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

If the home partition itself is too small, ask infrastructure to expand the volume.

(2) SSH config / ProxyJump / jump-host errors

This often blows up in environments that go through an internal security jump host. Terminal ssh reads the OS default config correctly, but VS Code can interpret the same settings differently and break the handshake.

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

The safest approach is to spell out the multi-hop explicitly in ~/.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

Then connect from VS Code to the target host. If it still fails, try toggling remote.SSH.useLocalServer in settings (see the later settings section).

(3) Server binary will not run because of glibc / old OS

This issue has exploded on EOL LTS servers such as CentOS 7 and Ubuntu 16.04. Symptoms: GLIBC_2.x not found and the server process exiting immediately.

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

Current VS Code Server requires a relatively recent glibc. There are three fix branches.

1. Pin a compatible VS Code version: Downgrade to an older VS Code that still supported that OS (e.g. before 1.85) and turn off automatic updates.
2. Use a legacy server option: Use a VS Code version that still offers legacy-build support.
3. Upgrade the OS: If possible, moving to a glibc 2.28+ environment (e.g. Ubuntu 20.04+, Rocky 8+) is the real fix.

(4) Corrupted ~/.vscode-server → delete and reinstall

This leftover state is common after an install was interrupted or after a disk filled up and was later freed. The typical symptom is Failed to connect to the remote extension host server.

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

For a cleaner approach from inside VS Code, run Command Palette (Ctrl/Cmd+Shift+P) → Remote-SSH: Kill VS Code Server on Host, then reconnect. On reconnect, the server is installed fresh automatically.

(5) Handshake fails because of firewall / abnormal shell RC (.bashrc) output

This trap is surprisingly common. VS Code runs commands in a non-interactive shell. If .bashrc or .profile prints echo output, banners, figlet, company security notices, and the like, the handshake data is polluted and you get Could not establish connection to.

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

The fix is to put a non-interactive early-return at the very top of .bashrc.

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

Also check whether outbound firewall rules block access to VS Code’s download servers (air-gapped networks need an offline install).

(6) Permissions / home-directory quota

If home-directory ownership flipped to root, or a disk quota is exceeded, the server cannot write files.

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

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

If quota is exceeded, you need the sysadmin to raise it. A single touch is the fastest way to tell whether writes work.

💬 From the field: the culprit I have seen most often is actually (5), polluted .bashrc output. Plenty of companies put a login banner in .bashrc for new-hire onboarding. The terminal still looks fine, but Remote-SSH fails in isolation. ssh user@host 'echo OK' catches it in five seconds. That is why, when I hit infinite loading, I run this command before I even check disk.

If it still fails: VS Code-side settings, cache reset, and toggles

If the remote server is healthy but the client is stuck in a retry loop, it is time to touch VS Code settings.

• Remote-SSH: Kill VS Code Server on Host: Run from the Command Palette to kill the server process and force a reinstall (see cause 4).
• If a local ~/.vscode/extensions conflict is suspected, disable the offending extension and reconnect.

Key settings (settings.json):

Order to break an infinite-loading retry loop: ① Click the connection status in the lower-right of the window → Close Remote Connection ② Kill VS Code Server on Host ③ On the remote, rm -rf ~/.vscode-server ④ Enable showLoginTerminal and reconnect to see the actual error.

Conclusion: 5-minute diagnostic checklist

Next time you get stuck, work top to bottom.

Tape this table to your desk and the next outage will not rattle you.

References: official docs

The primary sources for the behavior, settings, and errors in this post are the official docs below. Check them for version-specific options and exact behavior.

• OpenSSH sshd_config manual (man7.org)

FAQ

Q. ssh works, but VS Code is stuck in infinite loading. A. Authentication already succeeded; you are blocked at the ~/.vscode-server startup stage. Check df -h ~ (disk) and ssh user@host 'echo OK' (.bashrc pollution) first. One of those two is the cause in most cases.

Q. Is it safe to delete .vscode-server? A. Yes. It only holds cache, server binaries, and installed remote extensions. It does not affect your code or data. After rm -rf ~/.vscode-server, reconnect and it reinstalls automatically.

Q. We have to go through a company jump host. How should I configure that? A. Create a Host block in ~/.ssh/config with ProxyJump bastion and connect to that host (see the example in cause 2). If it still fails, try toggling remote.SSH.useLocalServer to false.

Q. We are on old CentOS/Ubuntu and get GLIBC_2.x not found. A. Check the glibc version with ldd --version. If it is below what current VS Code Server requires, pin a compatible older VS Code or upgrade the OS to a glibc 2.28+ environment.

Q. Install is blocked by a permission error. A. Check write access with touch ~/.vscode-server/test. If ownership is broken, restore it with sudo chown -R account:account ~/.vscode-server. If quota is exceeded, ask an admin to raise it.