Skip to content

SSH Connection Troubleshooting

Troubleshooting SSH connections

Unity relies on matching the public key stored in your Unity account to the private key on your host machine to authenticate SSH connections. Most connection errors come from not being able to match the keys appropriately.

Problem 1: ssh: Could not resolve hostname unity: Name or service not known

This error occurs when your connection doesn’t understand what you mean by `unity.'

This usually happens for one of two reasons:

  1. You haven’t yet set up your SSH config file (if that’s the case, see the SSH Documentation).
  2. You did set it up, but it is misplaced or misnamed.

If you have created your SSH config, verify:

  1. It is a file (not directory) named config with no extension.
  2. It is located in the directory /.ssh/.

Problem 2: Permission denied (publickey)

This problem means your SSH client and Unity can’t match the public key on Unity to the private key on your desktop.

First, verify that you’ve created SSH keys on the Unity portal or added an existing key to your Unity account. If you have done that, your SSH client must be configured to use your private key by specifying its location.

SSH can find keys with three methods:

  1. Inside the standard ~/.ssh directory in your home directory.
  2. From the IdentityFile line in your SSH config file.
  3. With the ssh -i ... option on the command line.

{{< callout >}} If you’re using the first two options but still get a permission denied error, try using the third option to verify that it’ll recognize the key. If this works, something’s wrong with your setup but not your key. {{< /callout >}}

Problem 3: Corrupted MAC on input

This issue affects Windows PowerShell users due to a bug in PowerShell’s version of SSH. This bug causes connection issues with newer OpenSSH installations when using Microsoft's SSH client included in PowerShell.

To fix this, Windows users using PowerShell SSH must add MACs hmac-sha2-512-etm@openssh.com to their ~/.ssh/config file, or use the flag option in your SSH command so that it reads ssh -m hmac-sha2-512-etm@openssh.com .

Edited by Julia Bragg