Diagnosing VS Code Remote‑SSH Connection Failures: Symptoms, Causes, and Fixes

Recognizable condition

When you try to open a remote folder with the Remote‑SSH extension, VS Code shows one of these messages in the notification area or the Remote‑SSH output panel:

• "Cannot establish SSH connection to <host>"
• "Timed out waiting for VS Code Server"
• "Failed to start the VS Code Server on the remote host"

The useful takeaway is that the problem is almost always rooted in one of three areas: SSH connectivity, remote‑host dependencies, or version incompatibility. By following the ordered checks below you can isolate the cause and apply the matching fix.

Cause & diagnostic table

Potential cause	Typical symptom	Quick verification step
Mis‑configured SSH host entry (wrong hostname, port, or missing IdentityFile)	SSH handshake fails immediately; output shows "ssh: connect to host … port 22: Connection refused" or "Host key verification failed"	Run ssh -vvv <host> from a local terminal and see if you can log in without password prompts.
Remote host missing required dependencies (glibc too old, Node.js absent, or VS Code Server binary not executable)	Connection succeeds but VS Code Server crashes; output contains "/usr/bin/code-server: line 1: /root/.vscode-server/bin/…/code-server: cannot execute binary file" or "GLIBC_2.28 not found"	After a successful SSH login, check the remote glibc version with ldd --version and verify Node.js with node -v. Then try to run the VS Code Server binary directly: ~/.vscode-server/bin/…/code-server --help.
Local network or firewall blocking outbound SSH (port 22) or the dynamic tunnel port used for the VS Code Server	SSH connection times out; ssh -vvv hangs at "Connection established…" and then aborts after a timeout.	From the client machine, test connectivity with nc -vz <host> 22 and, if needed, with a high port like nc -vz <host> 30000 (the VS Code Server tunnel picks a random high port).
Outdated Remote‑SSH extension or VS Code client causing incompatibility with the remote OS	Connection appears to work, but the output panel shows "Failed to download VS Code Server" or "Incompatible server version".	Check the extension version in VS Code (Extensions → @installed ms-vscode-remote.remote-ssh) and compare with the latest release on the Marketplace. Also verify the VS Code client version (Help → About).

Ordered verification steps

1. Test raw SSH connectivity

   Open a terminal on your local machine (no special permissions needed). Run:

   ssh -vvv <host-alias>

   Replace <host-alias> with the entry you use in VS Code (e.g., mydev). Look for a successful authentication and a remote shell prompt. If this fails, the issue is SSH‑level; proceed to the fixes in section 3.

   Risk: Exposing your private key if you accidentally use the wrong IdentityFile. Ensure the file referenced in ~/.ssh/config is readable only by you (chmod 600).

2. Confirm remote‑host dependencies

   Assuming SSH works, stay logged in and run:

   ldd --version
   node -v
   ~/.vscode-server/bin/*/code-server --help

   If any command reports “not found” or a GLIBC version error, the remote host lacks a required dependency.

3. Check for network/firewall blocks

   From the client, test:

   nc -vz <host> 22
   nc -vz <host> 30000

   Replace <host> with the IP or hostname. A successful nc reports "Connection to … port [tcp/*] succeeded!". If port 22 is blocked, you need to adjust your local firewall or corporate proxy. If the high port is blocked, the VS Code Server tunnel cannot be established.

4. Validate extension and client versions

   In VS Code:

   • Open the Extensions view (Ctrl+Shift+X) and search for "Remote‑SSH". Note the version.
   • Open Help → About to see the VS Code version.

   Compare both to the latest stable releases. If either is outdated, update them.

Fixes tied to findings

SSH config problems

Edit ~/.ssh/config (or the VS Code Remote‑SSH settings file) and correct the erroneous fields. Example of a correct entry:

Host mydev
    HostName dev.example.com
    Port 22
    User alice
    IdentityFile ~/.ssh/id_rsa_dev
    TCPKeepAlive yes
    ServerAliveInterval 30

After saving, test again with ssh -vvv mydev. Once the manual SSH login works, reload VS Code (Developer: Reload Window) and try opening the remote folder.

Missing remote dependencies

If glibc is too old, you have two options:

1. Upgrade the remote distribution to a version that provides GLIBC ≥ 2.28 (e.g., Ubuntu 20.04+, RHEL 8+).
2. Use the "Remote‑SSH: Use Legacy Server" setting (remote.SSH.useLocalServer false) to force VS Code to download a compatible server binary that bundles an older glibc.

If Node.js is missing, install it via the host’s package manager (apt-get install -y nodejs or yum install -y nodejs). After installation, repeat the dependency check from step 2.

Network or firewall blocks

Adjust your local firewall to allow outbound TCP on port 22 and on the high‑range ports used by the VS Code Server tunnel (default range 30000‑39999). On Linux with ufw:

sudo ufw allow out to any port 22 proto tcp
sudo ufw allow out to any port 30000:39999 proto tcp

On Windows, create outbound rules in Windows Defender Firewall. After changes, rerun the nc tests.
Extension/client version mismatch
Update the Remote‑SSH extension via the Extensions view (click the Update button). Update VS Code itself through Help → Check for Updates. Restart VS Code and retry the connection.
Escalation criteria
Escalate to a system administrator or file a GitHub issue when:

SSH works manually but the VS Code Server repeatedly crashes with a segmentation fault, indicating a possible binary incompatibility that cannot be resolved by updating glibc or Node.js.
Network tests show that outbound SSH is allowed, yet the VS Code Server tunnel never appears in the output panel (no "Forwarding server listening on …" line) despite a clean SSH login.
You are unable to upgrade the remote host’s OS due to corporate policy and the legacy server setting fails to start.

In these cases, capture the full Remote‑SSH output log (View → Output → Remote‑SSH) and include it in your report.
Practical way to verify the fix
After applying a fix:

Reload VS Code (Developer: Reload Window).
Attempt to open the remote folder again.
Watch the Remote‑SSH output panel for the line:

[Info  - 10:32:08.123] Forwarding server listening on 127.0.0.1:34567
If you see that line and the folder opens without error, the issue is resolved.