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 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.

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.

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