Fix: VS Code Remote SSH Could Not Establish Connection

The Error

You try to connect to a remote server using VS Code’s Remote - SSH extension and get:

Could not establish connection to "my-server". The VS Code Server failed to start.

Or:

Could not establish connection to "my-server". XHR failed

Or the connection window appears and then closes immediately with:

Failed to connect to the remote extension host server (Error: WebSocket close with status code 1006)

Or:

Resolver error: Error: Running the contributed command: '_workbench.downloadResource' failed.

Other symptoms:

• The SSH fingerprint prompt never appears — VS Code just times out.
• VS Code connects but the terminal shows “Waiting for server…” indefinitely.
• Connection worked before but broke after a VS Code update.
• Connection works with ssh from the terminal but not from VS Code.

Why This Happens

VS Code Remote SSH works by SSHing into the remote machine and downloading/running the VS Code Server — a small Node.js-based server process that handles language features, file access, and extension hosting. The local VS Code window is just a thin shell talking to that server over the SSH transport. When the connection fails, the failure can be at any of three layers: the SSH transport itself (the same layer as a plain ssh user@host command), the VS Code Server installation on the remote (download, extraction, permissions), or the server’s startup (port binding, Node.js execution, extension host crash).

The “Could not establish connection” message is the catch-all VS Code shows when any of those layers fails. To diagnose it, you have to know which layer broke. The “Remote-SSH: Show Log” command in the Command Palette is essential — it shows the literal SSH commands VS Code is running, the curl/wget commands it sends to download the server tarball, and any stderr output from the server’s startup. Without reading that log, you are guessing.

A version mismatch is the single most common cause. VS Code Server is pinned to the same commit hash as your local VS Code. When VS Code auto-updates locally, the next remote connection downloads a different commit’s server binary. If the download fails (offline server, firewall, expired DNS cache), you cannot connect — the previous server binary from the old commit is still on disk but VS Code refuses to talk to a mismatched version. Deleting ~/.vscode-server and reconnecting is the universal reset, which is why it works so often.

The connection fails when:

• The VS Code Server cannot be downloaded (network restrictions, no internet on server).
• The VS Code Server is corrupted or outdated (after a VS Code version mismatch).
• SSH config or key issues prevent the initial SSH connection.
• The remote machine lacks required software (glibc, tar, curl).
• The server process crashes or cannot start (permissions, disk space, memory).
• Firewall blocks the ports or connections VS Code needs.
• The remote home directory is full or the .vscode-server folder is corrupted.

Platform and Environment Differences

VS Code Remote SSH stitches together pieces from your local OS, your SSH client, the network in between, and the remote OS. Each of those layers has its own quirks.

Local OS — OpenSSH version. VS Code uses whatever ssh command is first in your PATH. On macOS, that is the system OpenSSH (currently 9.x). On Windows 10 1809+ and Windows 11, Microsoft ships OpenSSH as an Optional Feature — install it from Settings > Apps > Optional Features > OpenSSH Client. The OpenSSH version matters because older versions (7.x or earlier) do not support modern key types like ssh-ed25519 or modern ciphers used by hardened servers. Run ssh -V to check. If it is anything below 8.0, upgrade before debugging further.

Windows OpenSSH vs Git for Windows ssh.exe vs PuTTY plink. Three different ssh binaries can be installed on Windows simultaneously. VS Code uses whichever appears first in PATH, which depends on installation order. The Microsoft OpenSSH (C:\Windows\System32\OpenSSH\ssh.exe) is the most compatible. The Git for Windows OpenSSH (C:\Program Files\Git\usr\bin\ssh.exe) sometimes uses different key formats and a different known_hosts file. PuTTY’s plink.exe is incompatible with VS Code Remote SSH — it does not support all the same flags. Set remote.SSH.path in VS Code settings to point at the OpenSSH binary explicitly to avoid ambiguity.

WSL2 from Windows. If you run VS Code on Windows and want to connect to a server reachable only from WSL2, install the WSL extension instead. Trying to use Remote-SSH from Windows toward WSL2 itself works, but the connection target is localhost:2222 (or whatever you configured sshd to listen on inside WSL2). For a remote server that uses ProxyJump through WSL2, set remote.SSH.path to C:\\Windows\\System32\\OpenSSH\\ssh.exe and configure ProxyJump in your Windows ~/.ssh/config — VS Code does not run inside WSL2’s SSH agent.

ProxyJump vs ProxyCommand. ProxyJump bastion is the modern, recommended way to hop through a bastion. It works in OpenSSH 7.3+. ProxyCommand ssh -W %h:%p bastion is the older equivalent and works with any OpenSSH. VS Code respects both, but ProxyJump occasionally fails on Windows if the OpenSSH version is below 8.0 — fall back to ProxyCommand in that case.

SSH agent forwarding. Git operations on the remote often need your local SSH keys. Add ForwardAgent yes to the SSH config block for the host, and ensure your local agent is running (ssh-add -l to confirm keys are loaded). On Windows, the OpenSSH agent runs as a service — Get-Service ssh-agent should show Running. If the agent is stopped, even a working SSH connection will fail to authenticate git pushes from the remote terminal.

Port forwarding quirks. VS Code auto-forwards ports the remote process listens on. This is implemented via SSH dynamic port forwarding and the channel multiplexing built into OpenSSH. If the remote OpenSSH server has AllowTcpForwarding no in /etc/ssh/sshd_config, port forwarding silently fails — the connection itself works, but localhost:3000 on your laptop does not reach the remote dev server. Check the remote sshd_config if forwarded ports do not work.

GitHub Codespaces vs self-hosted. GitHub Codespaces uses its own protocol, not Remote-SSH — install the GitHub Codespaces extension instead. Codespaces handles version management automatically; the “delete .vscode-server” trick does not apply. Self-hosted remotes (your own EC2, Hetzner, lab box) are where Remote-SSH applies, and where almost every fix in this article matters.

ARM Linux remotes. Apple Silicon Macs connecting to ARM Linux servers (Raspberry Pi, Ampere, ARM64 EC2) work out of the box — VS Code downloads the server-linux-arm64 tarball. Intel Macs connecting to the same ARM server also work because VS Code chooses the right tarball based on the remote’s architecture, not the local one. Run uname -m on the remote; aarch64 means ARM64, armv7l means ARM32 (rarely supported by VS Code Server officially — for Raspberry Pi 4 use 64-bit Raspberry Pi OS).

Fix 1: Delete the VS Code Server on the Remote (Most Common Fix)

After a VS Code update, the local VS Code and the remote VS Code Server version mismatch. Deleting the server folder forces a fresh reinstall:

# SSH into the server manually
ssh user@your-server

# Delete the VS Code Server folder
rm -rf ~/.vscode-server

# Exit
exit

Then reconnect from VS Code. It will download and install a fresh copy of the server matching your current VS Code version.

Pro Tip: If you have multiple remote hosts, the VS Code Server folder is the same on all of them (~/.vscode-server). If you updated VS Code locally, you may need to clear the server on each remote host you connect to. The reinstall takes about 30–60 seconds depending on network speed.

For VS Code Insiders, the folder is ~/.vscode-server-insiders.

Fix 2: Fix SSH Connection Issues First

VS Code Remote SSH requires a working SSH connection. Verify the base SSH connection works from your terminal:

ssh -v user@your-server

The -v flag shows verbose output. Look for where it fails:

• “Connection refused”: The SSH daemon is not running or is blocked by a firewall.
• “Connection timed out”: Network issue or firewall blocking port 22.
• “Permission denied (publickey)”: Your SSH key is not authorized on the server.

For SSH key issues, see Fix: SSH Permission Denied (publickey) and Fix: SSH Connection Timed Out.

Check your SSH config file:

cat ~/.ssh/config

VS Code reads this file to know how to connect. A minimal working config for a server:

Host my-server
    HostName 192.168.1.100
    User ubuntu
    IdentityFile ~/.ssh/my-key.pem
    ServerAliveInterval 60
    ServerAliveCountMax 3

Make sure the Host name in your SSH config matches exactly what you type in VS Code’s “Remote-SSH: Connect to Host” prompt.

Fix 3: Install the Remote - SSH Extension and Check VS Code Version

Make sure you have the correct extension installed:

1. Open VS Code Extensions (Ctrl+Shift+X).
2. Search for Remote - SSH (publisher: Microsoft).
3. Install it if not already installed.
4. Also install Remote - SSH: Editing Configuration Files for easier config management.

The Remote - SSH extension requires VS Code 1.35 or later. The remote server requires the host to be running Linux (Windows and macOS remotes require Remote - SSH + additional setup or use Remote Tunnels instead).

Check VS Code version: Help > About. Update if you are more than a few versions behind — older VS Code versions may have bugs in the remote connection logic that have since been fixed.

Fix 4: Fix Download Failures on Air-Gapped or Restricted Servers

VS Code Server requires internet access to download itself the first time. If your server cannot reach the internet:

Option A: Use Remote-SSH: Configure Setting to skip verification

In VS Code settings (Ctrl+,), search for remote.SSH.useLocalServer and check the available options.

Option B: Download the server manually and copy it:

Find your VS Code commit ID:

• Help > About in VS Code, copy the Commit hash (e.g., abc1234...).

Download the VS Code Server for your platform:

# On your local machine
curl -L "https://update.code.visualstudio.com/commit:ABC123/server-linux-x64/stable" \
  -o vscode-server.tar.gz

Replace ABC123 with your commit hash and server-linux-x64 with server-linux-arm64 for ARM.

Copy it to the server and extract:

scp vscode-server.tar.gz user@your-server:~/
ssh user@your-server

mkdir -p ~/.vscode-server/bin/ABC123
tar -xzf ~/vscode-server.tar.gz -C ~/.vscode-server/bin/ABC123 --strip-components 1
touch ~/.vscode-server/bin/ABC123/0  # Signal that installation is complete

Option C: Use the Remote Tunnels feature (no direct SSH required):

VS Code Tunnels (code tunnel CLI) route the connection through Microsoft’s relay servers, bypassing direct network requirements. This is useful when the server is behind strict firewalls.

Fix 5: Fix Requirements on Minimal Linux Systems

The VS Code Server requires:

• glibc 2.17 or later (check: ldd --version)
• libstdc++ 6.0.21 or later
• tar (for extraction)
• curl or wget (for download)

On Alpine Linux or other musl-based systems, glibc is not available. VS Code Remote SSH does not officially support Alpine. Workarounds:

# Install gcompat on Alpine to add glibc compatibility layer
apk add --no-cache gcompat

Or use a glibc-compatible base image for your Docker container.

For Raspberry Pi or ARM systems, ensure you select the ARM version of VS Code Server. Check the architecture:

uname -m  # Should return aarch64 for ARM64 or armv7l for ARM32

Fix 6: Fix Permission and Disk Space Issues

The VS Code Server installs to ~/.vscode-server/ in the remote user’s home directory. Problems arise when:

Home directory is full:

df -h ~  # Check disk usage
du -sh ~/.vscode-server  # Check server folder size

If the disk is full, clear space or move the VS Code Server to a different location using the remote.SSH.serverInstallPath setting in VS Code.

Wrong permissions on .ssh or authorized_keys:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_rsa  # Or your key file

SSH is strict about permissions. Wrong permissions on key files cause authentication to silently fail.

The remote user does not have a shell. VS Code SSH needs a proper shell (/bin/bash or /bin/sh). Check:

grep "your-username" /etc/passwd
# Should show something like: username:x:1000:1000::/home/username:/bin/bash

Fix 7: Increase SSH Timeouts and Debug Connection

For slow networks or servers that take a long time to start:

In VS Code settings (Ctrl+,), add:

{
  "remote.SSH.connectTimeout": 60,
  "remote.SSH.serverInstallPath": {
    "my-server": "/home/user/.vscode-server-custom"
  }
}

Enable Remote SSH logging to diagnose the issue:

1. Open the Command Palette (Ctrl+Shift+P).
2. Run Remote-SSH: Show Log.
3. Reconnect and watch the log output.

The log shows exactly what VS Code is doing — which SSH command it runs, where the download fails, and what error the server reports. This is the fastest way to diagnose a non-obvious connection issue.

Force kill any stuck VS Code Server processes on the remote:

ssh user@your-server "pkill -f vscode-server; rm -rf ~/.vscode-server/bin"

This kills any running server process and clears the binary, forcing a clean reinstall on the next connection.

Fix 8: Fix Windows-Specific Issues

If your local machine is Windows:

Use OpenSSH from Windows, not PuTTY/Pageant. VS Code Remote SSH requires the system’s ssh command. Enable OpenSSH:

1. Settings > Apps > Optional Features > Add a Feature > OpenSSH Client.

Check that your SSH key is in the right format. VS Code on Windows uses OpenSSH format. PuTTY keys (.ppk) need to be converted with PuTTYgen (Conversions > Export OpenSSH key).

Check the SSH agent is running:

# In PowerShell (as Administrator)
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add C:\Users\YourUser\.ssh\id_rsa

Windows path issues. If your username contains spaces or special characters, the path to ~/.ssh/config may cause issues. Use the remote.SSH.configFile setting to point to an explicit path:

{
  "remote.SSH.configFile": "C:\\Users\\Your Name\\.ssh\\config"
}

Still Not Working?

Try connecting with a different SSH client first. If ssh user@server works in Terminal but not in VS Code, the issue is VS Code-specific. If both fail, the issue is in your SSH configuration or network.

Check for proxy or jump host requirements. If your server is behind a bastion/jump host, configure it in your SSH config:

Host my-server
    HostName 10.0.0.100
    User ubuntu
    ProxyJump [email protected]
    IdentityFile ~/.ssh/my-key.pem

Check if the server runs a compatible OS. VS Code Remote SSH officially supports Linux x64, ARM64, and ARMv7. Windows remotes require Windows Server 2019+ and a separate setup. macOS remotes are not officially supported.

Reinstall the Remote - SSH extension. Uninstall it, reload VS Code, then reinstall. Extension state can sometimes become corrupted after VS Code updates.

Check remote.SSH.useLocalServer and remote.SSH.lockfilesInTmp settings. On some Linux distros where the home directory is on NFS, the lockfiles VS Code Server uses for coordination get corrupted by NFS file locking semantics. Set "remote.SSH.lockfilesInTmp": true to put them in /tmp instead. This is a common fix for university and corporate Linux environments with networked home directories.

Check for SELinux or AppArmor blocking the server. On RHEL/CentOS with SELinux enforcing, the VS Code Server may not be able to bind to a port or write to certain paths. Check journalctl -t setroubleshoot and /var/log/audit/audit.log for AVC denials. The fix is usually chcon -R --type=user_home_t ~/.vscode-server.

Check that sshd allows enough sessions. OpenSSH MaxSessions defaults to 10. VS Code Remote SSH opens multiple multiplexed channels per connection — usually one or two, but extension hosting can push the count higher. If you also have multiple terminals open, you can hit the limit. Increase MaxSessions 30 in /etc/ssh/sshd_config on the remote and restart sshd.

Check for sudo requirements in the connection. If the remote shell starts with sudo or su to drop privileges, VS Code Server cannot find its working directory. The remote user must own ~/.vscode-server and have a normal login shell. See Fix: sudo: command not found if sudo issues are involved on the remote.

For git operations inside VS Code Remote sessions, if you encounter authentication issues, see Fix: git permission denied (publickey).