Troubleshooting SSH errors

Linux Windows

This document describes common errors that you may run into when connecting tovirtual machine (VM) instances using SSH, ways to resolve errors, andmethods for diagnosing failed SSH connections.

SSH troubleshooting tool

Use the SSH troubleshooting tool to help determine why an SSH connection failed.The troubleshooting tool performs the following tests to check for the cause offailed SSH connections:

  • User permissions tests: Checks if you have the required IAMpermissions to connect to the VM using SSH.
  • Network connectivity tests: Checks if the VM is connected to the network.
  • VM instance status tests: Checks the VM's CPU status to see if the VM isrunning.
  • VPC settings tests: Checks the default SSH port.

Run the troubleshooting tool

You can use the Google Cloud console or the Google Cloud CLI to check fornetworking problems and user permission errors that might cause SSHconnections to fail.

Permissions required for this task

To perform this task, you must have the followingpermissions:

  • networkmanagement.connectivitytests.create on the VM
  • networkmanagement.connectivitytests.delete on the VM
  • networkmanagement.connectivitytests.get on the VM

If you are missing any of the preceding permissions, the troubleshooting tool skips network connectivity tests.

Console

After an SSH connection fails, you have the option toRetry theconnection, orTroubleshoot the connection using the SSH-in-browsertroubleshooting tool.

To run the troubleshooting tool, clickTroubleshoot.

Launch SSH troubleshooting tool.

gcloud

Run the troubleshooting tool by using thegcloud compute ssh command:

gcloud compute sshVM_NAME \    --troubleshoot

ReplaceVM_NAME with the name of the VM that youcan't connect to.

The tool prompts you to provide permission to perform the troubleshootingtests.

Review the results

After running the troubleshooting tool, do the following:

  1. Review the test results to understand why the VM's SSH connection isn'tworking.
  2. Resolve SSH connections by performing the remediation steps provided bythe tool.

  3. Try reconnecting to the VM.

    If the connection isn't successful, try manually troubleshooting by doingthe following:

Common SSH errors

The following are examples of common errors you might encounter when you use SSHto connect to Compute Engine VMs.

SSH-in-Browser errors

Unauthorized Error 401

The following error might occur when you connect to your VM using theSSH-in-browser fromthe Google Cloud console:

UnauthorizedError 401

This error occurs if your user is part of an organization that ismanaged from within Google Workspace and there is an activerestriction in the Workspace policy that prevents users fromaccessing SSH-in-browser and the serial console within Google Cloud.

To resolve this issue, have a Google Workspace admin do the following:

  1. Confirm that Google Cloud is enabled for the organization.

    If Google Cloud is disabled, enable it and retry the connection.

  2. Confirm that services that aren't controlled individually are enabled.

    If these services are disabled, enable them and retry the connection.

If the problem persists after enabling Google Cloud settings inGoogle Workspace, do the following:

  1. Capture the network traffic in an HTTP Archive Format (HAR) file starting from when you start the SSH-in-Browser SSH connection.

  2. Create a Cloud Customer Care case and attach the HAR file.

Could Not Connect, Retrying...

The following error might occur when you start an SSH session:

Could not connect, retrying ...

Could not connect, retrying

To resolve this issue, do the following:

  1. After the VM has finished booting, retry the connection. If theconnection is not successful, verify that the VM did not boot inemergency mode by running the following command:

    gcloud compute instances get-serial-port-outputVM_NAME \| grep "emergency mode"

    If the VM boots in emergency mode, troubleshoot theVM startup process to identify where the boot process is failing.

  2. Verify that thegoogle-guest-agent.service service is running, by running the following command in theserial console.

    systemctl status google-guest-agent.service

    If the service is disabled, enable and start the service, by running the following commands:

    systemctl enable google-guest-agent.servicesystemctl start google-guest-agent.service

  3. Verify that the Linux Google Agent scripts are installed and running. For more information, seeDetermining Google Agent Status.If the Linux Google Agent is not installed,re-install it.

  4. Verify that you have the required roles to connect to the VM. If your VM uses OS Login, seeAssign OS Login IAM role. If the VM doesn't use OS Login, you need thecompute instance admin roleor theservice account user role (if the VM is set up to run as aservice account). The roles are needed to update the instance orproject SSH keys-metadata.

  5. Verify that there is a firewall rule that allows SSH access by running the following command:

    gcloud compute firewall-rules list | grep "tcp:22"

  6. Verify that there is a default route to the Internet (or to the bastionhost). For more information, seeChecking routes.

  7. Make sure that the root volume is not out of disk space. For more information, seeTroubleshooting full disks and disk resizing.

  8. Make sure the VM has not run out of memory, by running the following command:

    gcloud compute instances get-serial-port-output instance-name \| grep "Out of memory: Kill process" - e "Kill process" -e "Memory cgroup out of memory" -e "oom"

    If the VM is out of memory, connect toserial console to troubleshoot.

Linux errors

Permission denied (publickey)

The following error might occur when you connect to your VM:

USERNAME@VM_EXTERNAL_IP: Permission denied (publickey).

This error can occur for several reasons. The following are some of the mostcommon causes of this error:

  • You used an SSH key stored in metadata to connect to a VM that has OS Loginenabled. If OS Login is enabled on your project, your VM doesn't acceptSSH keys that are stored in metadata. If you aren't sure if OS Login isenabled, seeChecking if OS Login is configured.

    To resolve this issue, try one of the following:

  • You used an SSH key stored in an OS Login profile to connect to a VM thatdoesn't have OS Login enabled. If you disable OS Login, your VM doesn'taccept SSH keys that were stored in your OS Login profile. If you aren't sureif OS Login is enabled, seeChecking if OS Login is configured.

    To resolve this issue, try one of the following:

  • The VM has OS Login enabled, but you don't have sufficient IAM permissionsto use OS Login. To connect to a VM that has OS Login enabled, you must havethe permissions required for OS Login. If you aren't sure if OS Login isenabled, seeChecking if OS Login is configured.

    To resolve this issue,grant the required OS Login IAM roles.

  • Your key expired and Compute Engine deleted your~/.ssh/authorized_keysfile. If you manually added SSH keys to your VM and then connected to yourVM using the Google Cloud console, Compute Engine created a new key pair foryour connection. After the new key pair expired, Compute Enginedeleted your~/.ssh/authorized_keys file in the VM, which included yourmanually added SSH key.

    To resolve this issue, try one of the following:

  • You connected using a third-party tool and your SSH command ismisconfigured. If you connect using thessh command but don't specifya path to your private key or you specify an incorrect path to your privatekey, your VM refuses your connection.

    To resolve this issue, try one of the following:

    • Run the following command:
      ssh -iPATH_TO_PRIVATE_KEYUSERNAME@EXTERNAL_IP

      Replace the following:
      • PATH_TO_PRIVATE_KEY: the path to your private SSH key file.
      • USERNAME: the username of the user connecting to the instance. If you manage your SSH keys in metadata, the username is what you specified when youcreated the SSH key. ForOS Login accounts, the username is defined in your Google profile.
      • EXTERNAL_IP: The external IP address for your VM.
    • Connect to your VM using the Google Cloud console or the Google Cloud CLI. When you use these tools to connect, Compute Engine manages key creation for you. For more information, seeConnecting to VMs.

  • Your VM's guest environment is not running. If this is the first time thatyou are connecting to your VM and the guest environment is not running, thenthe VM might refuse your SSH connection request.

    To resolve this issue, do the following:

    1. Restart the VM.
    2. In the Google Cloud console, inspect the system startup logs in theserial port output to determine if the guest environment isrunning. For more information, seeValidating the guest environment.
    3. If the guest environment is not running, manuallyinstall the guestenvironment by cloning VM's boot disk and using a startup script.

  • The OpenSSH Daemon (sshd) isn't running or configured properly. Thesshd provides secure remote access to the system via SSH protocol. If it'smisconfigured or not running, you can't connect to your VM via SSH.

    Note: To troubleshoot the issue withsshd, you need toconnect to the VM's serial console as the root user.

    To resolve this issue, try one or more of the following:

    • Review the user guide for your operating system to ensure that yoursshd_config is set up correctly.

    • Ensure the you have the required ownership and permission settings for thefollowing:

      • $HOME and$HOME/.ssh directories
      • $HOME/.ssh/authorized_keys file

      Ownership

      The guest environment stores authorized SSH public keys in the$HOME/.ssh/authorized_keys file. The owner of the$HOME and$HOME/.sshdirectories and the$HOME/.ssh/authorized_keys file must be the same as theuser connecting to the VM.

      Permissions

      The guest environment requires the following Linux permissions:

      PathPermissions
      /home0755
      $HOME0700 or0750 or0755*
      $HOME/.ssh0700
      $HOME/.ssh/authorized_keys0600

      * To find out which of the options is the correct defaultpermission for your$HOME directory, refer to the official documentation foryour specific Linux distribution.

      Alternatively, you can create a new VM based on the same image and check itsdefault permissions for$HOME.

      To learn how to change permissions and ownership, read aboutchmod andchown.

    • Restart thesshd by running the following command:

      systemctlrestartsshd.service

      Check if there are any errors in the status by running the following command:

      systemctlstatussshd.service

      The status output may contain information such as the exit code, the reasonfor the failure, etc. You can use these details for further troubleshooting.

  • The VM's boot disk is full. When an SSH connection is established, theguest environment adds the session's public SSH key to the~/.ssh/authorized_keys file. If the disk is full, the connection fails.

    To resolve this issue, do one or more of the following:

  • The permissions or ownership on$HOME,$HOME/.ssh, or$HOME/.ssh/authorized_keys is wrong.

    Ownership

    The guest environment stores authorized SSH public keys in the$HOME/.ssh/authorized_keys file. The owner of the$HOME and$HOME/.sshdirectories and the$HOME/.ssh/authorized_keys file must be the same as theuser connecting to the VM.

    Permissions

    The guest environment requires the following Linux permissions:

    PathPermissions
    /home0755
    $HOME0700 or0750 or0755*
    $HOME/.ssh0700
    $HOME/.ssh/authorized_keys0600

    * To find out which of the options is the correct defaultpermission for your$HOME directory, refer to the official documentation foryour specific Linux distribution.

    Alternatively, you can create a new VM based on the same image and check itsdefault permissions for$HOME.

    To learn how to change permissions and ownership, read aboutchmod andchown.

Connection failed

The following errors might occur when you connect to your VM from theGoogle Cloud console, the gcloud CLI, a bastion host or a localclient:

  • The Google Cloud console:

    Connection FailedWe are unable to connect to the VM on port 22.

  • The gcloud CLI:

    ERROR: (gcloud.compute.ssh) [/usr/bin/ssh] exited with return code [255].

  • A bastion host or a local client:

    port 22: Connection timed out.
    port 22: Connection refused

These errors can occur for several reasons. The following are some of the mostcommon causes of the errors:

  • The VM is booting up andsshd is not running yet. You can'tconnect to a VM before it is running.

    To resolve this issue, wait until the VM has finished booting and try toconnect again.

  • sshd is running on a custom port. If you configuredsshd to run on aport other than port 22, you won't be able to connect to your VM.

    To resolve this issue, create a custom firewall rule allowingtcp traffic onthe port that yoursshd is running on using the following command:

    gcloud compute firewall-rules createFIREWALL_NAME \  --allow tcp:PORT_NUMBER

    For more information about creating custom firewall rules, seeCreating firewall rules.

  • The SSH firewall rule is missing or doesn't allow traffic fromIAP or the public internet. SSH connections are refused iffirewall rules do not allow connections from IAP or TCP ingresstraffic for IP range0.0.0.0/0.

    To resolve this issue, do one of the following:

    • If you use Identity-Aware Proxy (IAP) for TCP forwarding, update your customfirewall rule to accept traffic from IAP, then check your IAMpermissions.

      1. Update your custom firewall rule to allow traffic from35.235.240.0/20,the IP address range that IAP uses for TCP forwarding. Formore information, seeCreate a firewall rule.
      2. Grant permissions to use IAP TCP forwarding,if you haven't already done so.

    • If you don't use IAP update your custom firewall rule toallow ingress SSH traffic.

      1. Update your custom firewall rule toAllow ingress ssh connections to VMs.

  • The SSH connection failed after you upgraded the VM's kernel. A VM mightexperience a kernel panic after a kernel update, causing the VM to becomeinaccessible.

    To resolve this issue, do the following:

    1. Mount the disk to anotherVM.
    2. Update thegrub.cfg fileto use the previous version of the kernel.
    3. Attach the disk to theunresponsive VM.
    4. Verify that the status of the VM isRUNNING by using thegcloud compute instances describe command.
    5. Reinstall the kernel.
    6. Restart the VM.

    Alternatively, if you created a snapshot of the boot disk beforeupgrading the VM,use the snapshot to create a VM.

  • The OpenSSH Daemon (sshd) isn't running or configured properly. Thesshd provides secure remote access to the system via SSH protocol. If it'smisconfigured or not running, you can't connect to your VM via SSH.

    Note: To troubleshoot the issue withsshd, you need toconnect to the VM's serial console as the root user.

    To resolve this issue, try one or more of the following:

    • Review the user guide for your operating system to ensure that yoursshd_config is set up correctly.

    • Ensure the you have the required ownership and permission settings for thefollowing:

      • $HOME and$HOME/.ssh directories
      • $HOME/.ssh/authorized_keys file

      Ownership

      The guest environment stores authorized SSH public keys in the$HOME/.ssh/authorized_keys file. The owner of the$HOME and$HOME/.sshdirectories and the$HOME/.ssh/authorized_keys file must be the same as theuser connecting to the VM.

      Permissions

      The guest environment requires the following Linux permissions:

      PathPermissions
      /home0755
      $HOME0700 or0750 or0755*
      $HOME/.ssh0700
      $HOME/.ssh/authorized_keys0600

      * To find out which of the options is the correct defaultpermission for your$HOME directory, refer to the official documentation foryour specific Linux distribution.

      Alternatively, you can create a new VM based on the same image and check itsdefault permissions for$HOME.

      To learn how to change permissions and ownership, read aboutchmod andchown.

    • Restart thesshd by running the following command:

      systemctlrestartsshd.service

      Check if there are any errors in the status by running the following command:

      systemctlstatussshd.service

      The status output may contain information such as the exit code, the reasonfor the failure, etc. You can use these details for further troubleshooting.

  • The VM isn't booting and you can't connect using SSH or the serialconsole. If the VM is inaccessible, then your OS might be corrupted. If theboot disk doesn't boot, you candiagnose theissue.If you want to recover the corrupted VM and retrieve data, seeRecovering acorrupted VM or a full boot disk.

  • The VM is booting in maintenance mode. When booting in maintenance mode,the VM doesn't accept SSH connections, but you can connect to the VM's serialconsole and log in as the root user.

    To resolve this issue, do the following:

    1. If you haven't set a root password for the VM, use ametadata startup script to runthe following command during boot:

      echo 'root:NEW_PASSWORD' | chpasswd

      ReplaceNEW_PASSWORD with a password of your choice.

    2. Restart the VM.

    3. Connect to the VM's serial consoleand log in as the root user.

Unexpected error

The following error might occur when you try to connect to a Linux VM:

Connection FailedYou cannot connect to the VM instance because of an unexpected error. Wait a few moments and then try again.

This issue can occur for several reasons. The following are some common causesof the error:

  • The OpenSSH Daemon (sshd) isn't running or configured properly. Thesshd provides secure remote access to the system via SSH protocol. If it'smisconfigured or not running, you can't connect to your VM via SSH.

    Note: To troubleshoot the issue withsshd, you need toconnect to the VM's serial console as the root user.

    To resolve this issue, try one or more of the following:

    • Review the user guide for your operating system to ensure that yoursshd_config is set up correctly.

    • Ensure the you have the required ownership and permission settings for thefollowing:

      • $HOME and$HOME/.ssh directories
      • $HOME/.ssh/authorized_keys file

      Ownership

      The guest environment stores authorized SSH public keys in the$HOME/.ssh/authorized_keys file. The owner of the$HOME and$HOME/.sshdirectories and the$HOME/.ssh/authorized_keys file must be the same as theuser connecting to the VM.

      Permissions

      The guest environment requires the following Linux permissions:

      PathPermissions
      /home0755
      $HOME0700 or0750 or0755*
      $HOME/.ssh0700
      $HOME/.ssh/authorized_keys0600

      * To find out which of the options is the correct defaultpermission for your$HOME directory, refer to the official documentation foryour specific Linux distribution.

      Alternatively, you can create a new VM based on the same image and check itsdefault permissions for$HOME.

      To learn how to change permissions and ownership, read aboutchmod andchown.

    • Restart thesshd by running the following command:

      systemctlrestartsshd.service

      Check if there are any errors in the status by running the following command:

      systemctlstatussshd.service

      The status output may contain information such as the exit code, the reasonfor the failure, etc. You can use these details for further troubleshooting.

  • Unknown SSH daemon issue. To diagnose an unknown SSH daemon issue, checktheserial console logsfor errors.

    Depending on the output of the serial console logs, try to rescue the VMand fix the SSH daemon related issues by doing the following:

    1. Attach the disk to anotherLinux VM.
    2. Connect to the VM that has the mounted disk.
    3. Mount the diskinside OS to a directoryMOUNT_DIR inside VM..
    4. View the SSH-related logs,/var/log/secure or/var/log/auth.logfor any issues/errors. If you see any issues that you can fix, attempt tofix them. Otherwise,create a support caseand attach the logs.

    5. Unmount the disk from the OS usingumount command:

      cd ~/umount /mnt

    6. Detach the diskfrom the VM.

    7. Attach the diskto the original VM.

    8. Start the VM.

Failed to connect to backend

The following errors might occur when you connect to your VM from theGoogle Cloud console or the gcloud CLI:

  • The Google Cloud console:

    -- Connection via Cloud Identity-Aware Proxy Failed-- Code: 4003-- Reason: failed to connect to backend

  • The gcloud CLI:

    ERROR: (gcloud.compute.start-iap-tunnel) Error while connecting [4003: 'failed to connect to backend'].

These errors occur when you try to use SSH to connect to a VM that doesn't havea public IP address and for which you haven't configured Identity-Aware Proxy on port22.

To resolve this issueCreate a firewall rule onport 22 that allows ingress traffic from Identity-Aware Proxy.

Host key does not match

The following error might occur when you connect to your VM:

Host key for serverIP_ADDRESS does not match

This error occurs when the host key in the~/.ssh/known_hosts filedoesn't match the VM's host key.

To resolve this issue, delete the host key from the~/.ssh/known_hostsfile, then retry the connection.

Metadata value is too large

The following error might occur when you try to add a new SSH key to metadata:

ERROR:"Value for field 'metadata.items[X].value' is too large: maximum size 262144 character(s); actual sizeNUMBER_OF_CHARACTERS."

Metadata values have amaximum limit of 256 KB.To mitigate this limitation, do one of the following:

No supported authentication methods available

The following error might occur when you connect to a VM:

No supported authentication methods available (server sent: publickey,gssapi-keyex,gssapi-with-mic)

This error most commonly occurs due to an outdated SSH client. Older SSH clientsmight lack support for the ECDSA key types and SHA-2 hashing algorithms requiredby newer VMs.

For example, this error occurs if you try to connect to a Red Hat EnterpriseLinux (RHEL) VM using a version of PuTTY older than 0.75.

To resolve this error, update your SSH client to the most recent stable version.After you have updated your SSH client, retry your SSH connection.

Windows errors

Preview — SSH for Windows

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Permission denied, please try again

The following error might occur when you connect to your VM:

USERNAME@compute.INSTANCE_ID's password:Permission denied, please try again.

This error indicates the user trying to connect to the VM doesn't exist on theVM. The following are some of the most common causes of this error:

  • Your version of gcloud CLI is out of date

    If gcloud CLI is out of date, you may be attempting to connectusing a username that is not configured. To resolve this issue,update the gcloud CLI.

  • You tried to connect to a Windows VM that doesn't have SSH enabled.

    To resolve this error, set theenable-windows-ssh key toTRUE in projector instance metadata. For more information about setting medata, seeSet custom metadata.

Permission denied (publickey,keyboard-interactive)

The following error might occur when you connect to a VM that doesn't have SSHenabled:

Permission denied (publickey,keyboard-interactive).

To resolve this error, set theenable-windows-ssh key toTRUE in projector instance metadata. For more information about setting medata, seeSet custom metadata.

Could not SSH into the instance

The following error might occur when you connect to your VM from thegcloud CLI:

ERROR: (gcloud.compute.ssh) Could not SSH into the instance.It is possible that your SSH key has not propagated to the instance yet.Try running this command again.  If you still cannot connect, verify that the firewall and instance are set to accept ssh traffic.

This error can occur for several reasons. The following are some of the mostcommon causes of the errors:

  • You tried to connect to a Windows VM that doesn't have SSH installed.

    To resolve this issue, follow the instructions toEnable SSH for Windows on a running VM.

  • The OpenSSH Server (sshd) isn't running or isn't configured properly. Thesshd provides secure remote access to the system via SSH protocol. If it'smisconfigured or not running, you can't connect to your VM via SSH.

    To resolve this issue, reviewOpenSSH Server configuration for Windows Server and Windows to ensure thatsshd is set up correctly.

Connection timed out

Timed out SSH connections might be caused by one of the following:

  • The VM hasn't finished booting. Allow a short time for the VM to boot.

    To resolve this issue, wait until the VM has finished booting and try toconnect again.

  • The SSH package isn't installed. Windows VMs require you to install thegoogle-compute-engine-ssh package before you can connect using SSH.

    To resolve this issue,install the SSH package.

Diagnose failed SSH connections

The following sections describe steps you can take to diagnose the cause offailed SSH connections and the steps you can take to fix your connections.

Before you diagnose failed SSH connections, complete the following steps:

Diagnosis methods for Linux and Windows VMs

Test connectivity

You might not be able to SSH to a VM instance because of connectivity issueslinked to firewalls, network connection, or the user account. Follow the stepsin this section to identify any connectivity issues.

Check your firewall rules

Compute Engine provisions each project with a default set of firewallrules that permit SSH traffic. If you are unable to access your instance, usethegcloud compute command-line tool tocheck your list of firewallsand ensure that thedefault-allow-ssh rule is present.

On your local workstation, run the following command:

gcloud compute firewall-rules list

If the firewall rule is missing, add it back:

gcloud compute firewall-rules create default-allow-ssh \    --allow tcp:22

To view all data associated with thedefault-allow-ssh firewall rule in yourproject, use thegcloud compute firewall-rules describe command:

gcloud compute firewall-rules describe default-allow-ssh \    --project=project-id

For more information about firewall rules, seeFirewall rules in Google Cloud.

Test the network connection

To determine whether the network connection is working, test the TCP handshake:

  1. Obtain the externalnatIP for your VM:

    gcloud compute instances describeVM_NAME \    --format='get(networkInterfaces[0].accessConfigs[0].natIP)'

    ReplaceVM_NAME with the name of the VM you can'tconnect to.

    Note: The IP address may vary if you are using IAP to access the instance viathe internal IP address. Also, if the IP address is internal, the instanceis accessible from inside the VPC network only.

  2. Test the network connection to your VM from your workstation:

    Linux, Windows 2019/2022, and macOS

    curl -vso /dev/null --connect-timeout 5EXTERNAL_IP:PORT_NUMBER

    Replace the following:

    • EXTERNAL_IP: the external IP address youobtained in the previous step
    • PORT_NUMBER: the port number

    If the TCP handshake is successful, the output is similar to the following:

    Expire in 0 ms for 6 (transfer 0x558b3289ffb0)Expire in 5000 ms for 2 (transfer 0x558b3289ffb0)Trying 192.168.0.4...TCP_NODELAY setExpire in 200 ms for 4 (transfer 0x558b3289ffb0)Connected to 192.168.0.4 (192.168.0.4) port 443 (#0)> GET / HTTP/1.1> Host: 192.168.0.4:443> User-Agent: curl/7.64.0> Accept: */*>Empty reply from serverConnection #0 to host 192.168.0.4 left intact

    TheConnected to line indicates a successful TCP handshake.

    Windows 2012 and 2016

    PS C:> New-Object System.Net.Sockets.TcpClient('EXTERNAL_IP',PORT_NUMBER)

    Replace the following:

    • EXTERNAL_IP: the external IP you obtained inthe previous step
    • PORT_NUMBER: the port number

    If the TCP handshake is successful, the output is similar to the following:

    Available           : 0Client              : System.Net.Sockets.SocketConnected           : TrueExclusiveAddressUse : FalseReceiveBufferSize   : 131072SendBufferSize      : 131072ReceiveTimeout      : 0SendTimeout         : 0LingerState         : System.Net.Sockets.LingerOptionNoDelay             : False

    TheConnected: True line indicates a successful TCP handshake.

If the TCP handshake completes successfully, a software firewall rule isnot blocking the connection, the OS is correctly forwarding packets, and aserver is listening on the destination port. If the TCP handshake completessuccessfully but the VM doesn't accept SSH connections, the issue might bewith that thesshd daemon is misconfigured or not running properly. Reviewthe user guide for your operating system to ensure that yoursshd_config is set up correctly.

To run connectivity tests for analyzing the VPC network path configurationbetween two VMs and check whether the programmed configuration should allow thetraffic, seeCheck for misconfigured firewall rules in Google Cloud.

Connect as a different user

The issue that prevents you from logging in might be limited to your useraccount. For example, the permissions on the~/.ssh/authorized_keys fileon the instance might not be set correctly for the user.

Try logging in as a different user with the gcloud CLI byspecifyingANOTHER_USERNAME with the SSH request.The gcloud CLI updates the project's metadata to add thenew user and allow SSH access.

gcloud compute sshANOTHER_USERNAME@VM_NAME

Replace the following:

  • ANOTHER_USERNAME is a username other than your ownusername
  • VM_NAME is the name of the VM you want to connect to

Debug issues using the serial console

We recommend that you review the logs from theserial console forconnection errors. You can access the serial console as the root user from yourlocal workstation by using a browser. This approach is useful when you cannotlog in with SSH, or if the instance has no connection to the network. The serialconsole remains accessible in both of these situations.

To log into the VM's serial console and troubleshoot problems with the VM,follow these steps::

  1. Enable interactive access to the VM's serial console.

  2. For Linux VMs, modify the root password, add the followingstartup script to your VM:

    echoroot:PASSWORD|chpasswd

    ReplacePASSWORD with a password of your choice.

  3. Use the serial console toconnect to your VM.

  4. For Linux VMs, after you're done debugging all the errors, disable the root account login:

    sudopasswd-lroot

Diagnosis methods for Linux VMs

Inspect the VM instance without shutting it down

You might have an instance that you cannot connect to that continues tocorrectly serve production traffic. In this case, you might want to inspectthe disk without interrupting the instance.

To inspect and troubleshoot the disk:

  1. Back up your boot disk bycreating a snapshot of the disk.
  2. Create a regular persistent disk from that snapshot.
  3. Create a temporary instance.
  4. Attach and mount the regular persistent disk to your new temporary instance.

This procedure creates an isolated network that only allowsSSH connections. This setup prevents any unintended consequences of thecloned instance interfering with your production services.

  1. Create a new VPC network to host your cloned instance:

    gcloud compute networks create debug-network

    ReplaceNETWORK_NAME with the name you want to callyour new network.

  2. Add a firewall rule to allow SSH connections to the network:

    gcloud compute firewall-rules create debug-network-allow-ssh \   --network debug-network \   --allow tcp:22

  3. Create a snapshot of the boot disk.

    gcloud compute disks snapshotBOOT_DISK_NAME \   --snapshot-names debug-disk-snapshot

    ReplaceBOOT_DISK_NAME with the name of the bootdisk.

  4. Create a new disk with the snapshot you just created:

    gcloud compute disks create example-disk-debugging \   --source-snapshot debug-disk-snapshot

  5. Create a new debugging instance without an external IP address:

    gcloud compute instances create debugger \   --network debug-network \   --no-address

  6. Attach the debugging disk to the instance:

    gcloud compute instances attach-disk debugger \   --disk example-disk-debugging

  7. Follow the instructions toConnect to a VM using a bastion host.

  8. After you have logged into the debugger instance, troubleshoot the instance.For example, you can look at the instance logs:

    sudo su -
    mkdir /mnt/VM_NAME
    mount /dev/disk/by-id/scsi-0Google_PersistentDisk_example-disk-debugging /mnt/VM_NAME
    cd /mnt/VM_NAME/var/log
    # Identify the issue preventing ssh from workingls

    ReplaceVM_NAME with the name of the VM you can'tconnect to.

Use a startup script

If none of the preceding helped, you can create a startup script to collectinformation right after the instance starts. Follow the instructions forrunning a startup script.

Afterward, you also need to reset your instance before the metadata takeseffect by usinggcloud compute instances reset.

Alternatively, you can also recreate your instance by running a diagnosticstartup script:

  1. Rungcloud compute instances delete with the--keep-disks flag.

    gcloud compute instances deleteVM_NAME \   --keep-disks boot

    ReplaceVM_NAME with the name of the VM you can'tconnect to.

  2. Add a new instance with the same disk and specify your startup script.

    gcloud compute instances createNEW_VM_NAME \   --disk name=BOOT_DISK_NAME,boot=yes \   --metadata startup-script-urlURL

    Replace the following:

    • NEW_VM_NAME is the name of the new VM you'recreating
    • BOOT_DISK_NAME is the name of the boot disk fromthe VM you can't connect to
    • URL is the Cloud Storage URL to thescript, in eithergs://BUCKET/FILE orhttps://storage.googleapis.com/BUCKET/FILEformat.

Use your disk on a new instance

If you still need to recover data from your persistent boot disk, you candetach the boot disk and then attach that disk as a secondary disk on anew instance.

  1. Delete the VM you can't connect to and keep its boot disk:

    gcloud compute instances deleteVM_NAME \   --keep-disks=boot

    ReplaceVM_NAME with the name of the VM you can'tconnect to.

  2. Create a new VM with your old VM's boot disk.Specify the name of the boot disk of the VM you just deleted.

  3. Connect to your new VM using SSH:

    gcloud compute sshNEW_VM_NAME

    ReplaceNEW_VM_NAME with the name of your new VM.

Check whether or not the VM boot disk is full

Your VM might become inaccessible if its boot disk is full. This scenario can bedifficult to troubleshoot as it's not always obvious when the VM connectivityissue is due to a full boot disk. For more information about this scenario,seeTroubleshooting a VM that is inaccessible due to a full boot disk.

Diagnosis methods for Windows VMs

Preview — SSH for Windows

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Reset SSH metadata

If you can't connect to a Windows VM using SSH, try unsetting theenable-windows-ssh metadata key and re-enabling SSH for Windows.

  1. Set theenable-windows-ssh metadata key toFALSE. For information abouthow to set metadata, seeSet custom metadata.

    Wait a few seconds for the change to take place.

  2. Re-enable SSH for Windows

  3. Reconnect to the VM.

Connect to the VM using RDP

If you can't diagnose and resolve the cause of failed SSH connections to yourWindows VM,connect using RDP.

After you establish a connection to the VM, review theOpenSSH logs.

What's Next?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-09 UTC.