Troubleshooting server issues in Deploy

Tips & Tricks

There are a number of issues you might run into when adding a new server to your Deploy project, which we'll be outlining further in this post. To start, we'll look at how Deploy processes and validates a new server when it's added, and how errors relating to that process can be diagnosed and resolved.

When you configure a new server, whether it's using SSH/SFTP, FTP or another protocol such as S3, Deploy always goes through the same steps when checking it.


Firstly, we'll check that we can connect to your server using the chosen protocol and provided authentication details, which verifies the following:

  • That Deploy's servers can initially connect to your server - ensuring no firewall rules might be in place stopping connections from succeeding.
  • That Deploy can authenticate correctly on your server with the details provided, whether that's a username and password, or an SSH key.

Deployment directory and file permissions

Once a connection has been opened successfully, Deploy will change to the directory you've configured for your Server path if needed, then upload and remove a test file. This verifies the following:

  • That the directory provided exists on the server and that the user configured in Deploy has access to it
  • That the user can write to the directory

If the tests pass, your server will be added and you can run a deployment. This test can be performed at any time in the project - just head to your General Settings page via the Settings dropdown and click Run tests on the right hand side. If any servers fail these tests you'll be notified and you can investigate further.

Next, we'll be looking further at errors that can occur during these stages and how they can be resolved.

Connection - timeouts

The most common symptom displayed when there is a connection timeout in Deploy is the following:

Server did not respond within 45 seconds

Normally this is as a result of a firewall issue on your server. It's encouraged to check that our IP ranges have been allowed through your server's firewall, which are displayed at all times in your server's configuration page, and also in our documentation.

If you're happy that you have no firewall-related issues, it's advisable to try connecting via a local client with your configured protocol, or via a terminal. If you've provided a hostname, it's not uncommon to find a problem connecting via IPv6, but that a connection succeeds via IPv4. In cases such as this you can use your IPv4 address in Deploy temporarily whilst you resolve any issues with IPv6.

Connection - authentication errors

The next step is authentication, where if it fails you'll find the following error displayed:

We couldn't access this server using the credentials you have provided.

Followed by either of the next errors, depending on what type of authentication you've tried to configure:

Have you uploaded the appropriate public key onto the server?

Have you entered the username & password correctly?

If you're using SSH keys, you'll need to ensure that the project's public key is uploaded to your user's authorized_keys file on your server, and the permissions of ~/.ssh and authorized_keys are set to 700 and 600 respectively.

With the latter error, it's always prudent to double check your username and password have indeed been entered correctly, and also to try connecting to the server using a local client with the same details, to ensure you can authenticate through there as well.

Directory and files - permission errors

After the authentication stage, Deploy will upload a test file to your deployment directory. If one has been specified Deploy will change to it first, otherwise it'll use the directory you initially login to, then the test file will be uploaded and deleted. If this process fails, you'll see the following error:

We couldn't write to the server. Check that the path/container you have entered exists and that the user has write access.

We will now go through two main checks that can be made if this error occurs.

Directory and files - directory existence

If a deployment directory has been specified, you should first check to ensure the directory exists on the server, and that the user has access to it. This can be easily verified using an FTP/SFTP client.

In some cases, in particular with a shared hosting provider, accounts may be jailed to a certain subdirectory on the server, not allowing access to the server's root. In these cases it can best to login with the Deploy user and check which directory is reached initially, then add a relative path based on that in Deploy.

Otherwise, a simple test can be performed by logging in using a terminal, then attempting to cd to the directory you've attempted to configure. If it doesn't exist, you'll be presented with an error straight away:

$ cd /path/to/directory
-bash: cd: /path/to/directory: No such file or directory

Directory and files - file permissions

If you're happy that the directory does exist and the user can access it, you'll need to next ensure the user has permissions to write to it. Running ls -l /path/to/directory on your server will give you an immediate idea of this. For example, the following permissions would mean your user has no write access:

$ ls -ld /var/www/my-site
drwxr-xr-x     4 root  root    1462 11 Apr 16:27 my-site

The above permissions show that read and write access has only been granted to the root user, meaning any other user that attempts to write to the directory will be unable to. More information about file permissions can be found in this excellent article.

If you need to change permissions and have access to be able to do so; you can use the chown or chmod commands, as appropriate depending on if you need to change the file/folder owner, or just the level of permissions. Using the example above, you can run the following to update the directory owner, ensuring only your deployment user can write to the directory:

chown deployuser:deployuser /var/www/my-site

That will set the owner and user group of my-site to deployuser, meaning that DeployHQ can write to the directory. A typical example of the chmod command might look like:

chmod 755 deployuser /var/www/my-site

That'll give full read, write and execute access to the directory owner, but only read and execute access to the user group and anyone else.

We recommend further reading about both chown, and chmod for changing individual file and folder permissions which also has a handy calculator for determining the appropriate octal bits to send.

FTP - Passive connections

When using an FTP connection, some servers may be set up to use Passive (PASV) mode for data connections, which may cause the same issues with writing files. You can enable PASV mode by checking the Use passive (PASV) mode option in your server settings when adding or updating it.


We hope you have found these troubleshooting steps useful, we have a number of articles in our main Common Deployment Errors section in Deploy's documentation, but you can always drop us an email if you're stuck getting your server added, then we'll be happy to help you go through the steps.

A little bit about the author

I'm Adam W, or as everyone prefers to call me - Batman. I get a lot of satisfaction out of helping our customers and am committed to making their customer experience as positive as possible. When not offering support to our customers, you'll find me gaming, listening to music or running.

Proudly powered by Katapult. Running on 100% renewable energy.