Troubleshooting

What a message means and what to do about it, from Connection Doctor's findings to sign-in problems.

Updated

When a connection fails, its tab shows which stage failed. Click Diagnose to open Connection Doctor: it checks that the VM is running and finished booting, that you have the IAP tunnel role and that the port is reachable, names the cause, and gives a command to Copy. Fix it, then click Retry after fix.

Ostgate saysWhat to do
Missing IAP tunnel role Grant the account roles/iap.tunnelResourceAccessor on the instance or project.
No route to the VM port Allow ingress from 35.235.240.0/20 to that port (see Prepare your project) and check that something listens on it on the VM.
VM still starting up Wait a minute for Windows or sshd to finish booting, then reconnect.
Instance not running Start the instance, then reconnect.
Network interface not found The instance has no interface by that name; pick one of those listed.
Instance or zone lookup failed (4047/4051) IAP could not find the instance, or the network interface the tunnel asks for. Check that the instance still exists in that zone, and that the tunnel's Interface is one the instance has, or use nic0.
Refused … — only Ostgate may connect The tunnel's or forward's access setting turned that program away. Choose Change Access… on the notice and pick My processes to let your own apps in (see Tunnels and forwards).
Port … is already in use on this Mac Another program listens on that local port. Choose another local port, or stop the old listener in Local › Local Ports.
Needs Compute Viewer role (or Cloud SQL Viewer, Cloud Run Viewer) The account can't list that project's resources. Select the project's row: the inspector names the missing permission, and Open IAM in Cloud Console opens the project's IAM page to grant the role. Copy Details gives you the text to send to whoever administers the project.
Permission denied Grant the IAM role that the call requires (see the roles table), then retry.
Can't publish SSH key Grant roles/compute.instanceAdmin.v1 on the instance, or enable OS Login on it.
Host key mismatch If the VM was rebuilt, choose Forget Stored Key and reconnect. Otherwise do not connect until you know why the key changed.
SSH password rejected / SSH password not accepted Check the username and password. If they are right, the VM may not allow password logins.
Password login not offered Turn on PasswordAuthentication in the VM's sshd, or set SSH auth to Automatic or a key file.
RDP sign-in rejected Generated passwords expire quickly: use Set Windows Password… again and retry.
VM requires NLA Turn NLA on in connection settings, then retry.
Restricted Admin refused Turn Restricted Admin off in connection settings, or enable the mode on the VM.
… is not enabled in this project Enable that API in the project (see Prepare your project). Selecting the project's row offers Enable API in Cloud Console.
… needs you to sign in again Google refused the account's sign-in. Click Sign In Again…. The account's open sessions keep running meanwhile.
… can't be reached Your Mac has no network, or a proxy or Google's sign-in service didn't answer. You don't need to sign in: the account is checked again by itself when the network returns, or click Check Again. Lists show the last known state until then.
Connection lost · relay code … The tab's tunnel ended, for example after your Mac slept or the network was down for more than a few minutes. Click Reconnect once the network is back; a Files tab comes back in the same folder.
New connections are off The trial or licence has ended; see Licence.