Troubleshooting VSCode SSH connectivity issues

Last updated: June 25, 2026

Sometimes as a Coder system administrator, you will need to troubleshoot network connectivity issues around communication with a local IDE and the remote Coder workspace. This guide discusses steps to take and information to gather to help the Coder Support and Engineering teams help troubleshoot and potentially remediate your issues as quickly as possible.

Examine the template to explore useful logging

  • Is the workspace running on a virtual machine or in a containerized environment?
  • Can you obtain the logging from the host running the workspace?
    • /var/log/syslog
    • /var/log/cloud-init.log
    • /var/log/clout-init-output.log

Expand the context around the developer's issue

  • Has it always been like this for the developer or is this a new behavior?
  • If this is new:
    • Have any of the applications been updated?
      • Coder
      • Local VSCode
      • Workspace VSCode
    • Have there been any network changes that could impact this user uniquely?
    • Have they tried to replicate the experience on different networks to rule out a local network effect that might be impacting them?

Obtain more information about the developer's workstation

  • What OS and version are they running?
    • If Windows, what SSH implementation are they using?
    • What version of SSH?
  • What version of VSCode?
  • Do they have anything running that might impact a network connection, i.e.:
    • VPN software
    • local firewall applications
    • stateful packet inspectors (CrowdStrike, Sentinel)
    • Session-table based NAT devices
    • Custom SSH agents (1Password CLI, etc)

Collect additional information that could help with troubleshooting

Ask that before being disconnected, the developer:

  • Enable additional SSH logging for the Coder Extension.
    • Create a directory to store the logs in, for example ${HOME}/proxy_logs.
    • Set the Coder: Proxy Log Directory user VSCode preference to the name of the folder you
      created, such as ${userHome}/proxy_logs.
    • !!Restart VSCode to activate the new setting.

Ask that after being disconnected, the developer:

  • Collect the local VSCode logs. For more information, see
    Collecting Client-Side Debug Logs in Visual Studio Code.
  • Collect the workspace-side VSCode server logs. These are likely in /tmp/vscode-web.log; however, you can usually see the log path in the workspace agent's startup-log.txt.
  • If a Windows workstation, check the Windows Event Logs to see if there are any logs that might appear to be related.
  • If a Linux workstation, check the system logs for any potentially related events.
  • Run through the Microsoft Remote-SSH troubleshooting steps here:
    https://github.com/microsoft/vscode-remote-release/wiki/Remote-SSH-troubleshooting
  • Collect the logs from the Coder: Proxy Log directory.