Upsun User Documentation

Troubleshoot SSH

Sign up

Get your free trial by clicking the link below.

Get your Upsun free trial

While trying to use SSH, you may get a response indicating permission is denied. Or if you get an error with a code of 255, it means there’s a problem with your SSH connection.

The command failed with the exit code: 255

There are several places to check to try to solve such issues.

Check your environment Anchor to this heading

If your environment is inactive or the deployment has failed, you can’t log in to it. To make sure the environment is active and the deployment has succeeded, check it using upsun environment:list or in the Console .

Redeploy your environment Anchor to this heading

If you have just added your SSH key or made changes to access rules, you need to redeploy your environment before you can access it using SSH keys. You can do this in the Console, by running upsun redeploy, or by pushing an empty git commit:

git commit --allow-empty -m 'chore: force redeploy'
git push origin main

Check your public key Anchor to this heading

Make sure your public key has been uploaded to your user account. Check it in the Upsun Console.

SSH key can not be duplicated Anchor to this heading

A given SSH key pair can only be linked to a single user account. If you add an already used SSH key to another account, you see the error: SSH key can not be duplicated. Generate a new pair of SSH keys for the second user account you want to add.

Check your SSH agent Anchor to this heading

Check that your key is properly added to your SSH agent. This is an authentication agent that manages your private key.

  1. Run ssh-add -l in your terminal:

    ssh-add -l

    You get output similar to the following:

    2048 12:b0:13:83:7f:56:18:9b:78:ca:54:90:a7:ff:12:69 /Users/your_username/.ssh/id_rsa (RSA)
  2. Check that the file exists and that the file name or comment matches your private key file.

  3. If you don’t see your private key file, add your private key:

    ssh-add path-to-your-key

Specify your identity file Anchor to this heading

If your identity (SSH key) associated with Upsun isn’t in a default file name (as may be explained in your SSH software manual, for example), you may have to append a specification like the one below so that the SSH software finds the correct key.

IdentityFile ~/.ssh/id_upsun

Be aware that, above, upsun stands for a hostname. Each different hostname you connect to Upsun at may have to be specified in the host line, separated by spaces.

Check your Git integrations Anchor to this heading

If your project is integrated with another Git provider (such as GitHub), that provider controls Git operations. Make sure you have added your public SSH key to your provider and that your user there has access.

Generate SSH debug information Anchor to this heading

If your private key and public key both look OK but you don’t have any luck logging in, print debugging information. These lines often give clues about what’s going wrong.

Run the SSH command with the -v option, like so:

ssh -v [SSH-URL]

You get output similar to the following:

OpenSSH_6.7.8, OpenSSL 1.2.3 1 Sep 2014
debug1: Connecting to [] port 22.
debug1: Connection established.
debug1: identity file /Users/your_username/.ssh/id_rsa type 1
...(many more lines of this light reading)...
debug1: Offering RSA public key: /Users/your_username/.ssh/id_rsa
debug1: Authentications that can continue: publickey
debug1: No more authentication methods to try.
Permission denied (publickey).

Alternatively, you can run the following command:

GIT_SSH_COMMAND="ssh -v" git clone REPO_URL

You can use this information to make one last check of the private key file.

If you haven’t enabled MFA on your user account and try to SSH into an environment that is protected by MFA, you get the following error message:

Error: Access denied
Service: abcdefg123456-main-bvxea6i--app
Parameters: {"amr":["mfa"]}
Detail: Additional authentication is required:
	 - Multi-factor authentication (MFA)

To solve this, enable MFA on your user account.

Alternatively, open the Console and select the desired organization. Follow the instructions so you can effectively access its contents.

Similarly for bot users and CLI tokens, you may see the message:

  Multi-factor authentication (MFA) is required.               
  The API token may need to be re-created after enabling MFA.  

In this case, as described, it will be necessary to:

  1. Enable MFA on the (bot) user account associated with the token.
  2. Generate a new access token, and then replace its value in your workflow that requires the token (such as updating a GitHub workflow secret variable).

Something still wrong? Anchor to this heading

For more general information, see how to troubleshoot development.

If you’re still stuck, open a support ticket and provide the full SSH debug information.

Is this page helpful?