There are a number of issues you might run into when adding a new server to your DeployHQ project. In this guide, we'll walk through how DeployHQ validates a new server connection, the most common errors you'll encounter, and how to diagnose and resolve each one.
Whether you're seeing connection timeouts, authentication failures, or permission denied errors, this guide covers the fixes.
When you configure a new server — whether it's using SSH/SFTP, FTP, or another protocol such as S3 — DeployHQ always runs through the same validation steps.
Step 1: Connection test
First, DeployHQ checks that it can connect to your server using the chosen protocol and the authentication details you've provided. This verifies:
- That DeployHQ's servers can reach your server — ensuring no firewall rules are blocking the connection
- That DeployHQ can authenticate with the credentials you've provided, whether that's a username and password or an SSH key
Step 2: Deployment directory and file permission test
Once the connection succeeds, DeployHQ changes to your configured Server path (if one is set), then uploads and removes a test file. This verifies:
- That the directory exists on the server and your user has access to it
- That the user can write files to the directory
If both tests pass, your server is added and you can run a deployment. You can re-run these tests at any time from Settings > General Settings by clicking Run tests next to your server.
Now let's look at each error you might encounter and how to resolve it.
Fixing connection timeouts
The most common connection error in DeployHQ looks like this:
Server did not respond within 45 seconds
This almost always indicates a firewall issue on your server. Here's how to fix it:
1. Allow DeployHQ's IP addresses through your firewall
DeployHQ connects from specific IP ranges that are shown on your server's configuration page within your project. You can also find them in the DeployHQ firewall documentation. Make sure these IPs are allowed through any firewall, security group, or network ACL on your server.
2. Test the connection locally
Try connecting to your server from your own machine using the same protocol (SSH, SFTP, or FTP). If the connection works locally but fails from DeployHQ, the firewall is almost certainly the issue.
3. Check for IPv6 issues
If you've provided a hostname, it's not uncommon to find that IPv6 connections fail while IPv4 works fine. Try using your server's IPv4 address directly in DeployHQ while you resolve any IPv6 configuration issues.
4. Enable passive mode for FTP
If you're using FTP, enable Passive mode (PASV) in your server configuration within DeployHQ. This resolves issues where the data connection port is blocked.
Related: If you're unsure which file transfer protocol to use, see our guide on the differences between FTP, FTPS and SFTP.
Fixing authentication errors
If the connection succeeds but authentication fails, you'll see:
We couldn't access this server using the credentials you have provided.
Followed by one of these messages:
Have you uploaded the appropriate public key onto the server?
Have you entered the username & password correctly?
SSH key authentication
If you're using SSH key authentication, check the following:
Copy the correct public key: Each DeployHQ project has a unique SSH public key. Copy it from your project's server configuration page and add it to
~/.ssh/authorized_keyson your server.Set the correct file permissions: SSH is strict about permissions. Run these commands on your server:
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
If the permissions are wrong, SSH will silently refuse the key and the connection will fail. This is one of the most common causes of authentication errors.
- Check the authorized_keys format: Make sure the key is on a single line with no line breaks. Each key should be one continuous line starting with
ssh-rsaorssh-ed25519.
Related: For a deeper dive into SSH key issues, see our guide to creating and managing SSH keys.
Password authentication
For password-based authentication:
- Double-check that the username and password are entered correctly in DeployHQ — copy-paste errors with trailing spaces are common
- Try logging into your server from a local terminal or FTP client with the same credentials
- Check that password authentication is enabled in your server's SSH configuration (
PasswordAuthentication yesin/etc/ssh/sshd_config)
Fixing directory and file permission errors
After authentication, DeployHQ uploads a test file to your deployment directory. If this fails, you'll see:
We couldn't write to the server. Check that the path/container you have entered exists and that the user has write access.
There are two common causes.
The directory doesn't exist
If you've specified a deployment path, verify the directory actually exists on your server:
cd /path/to/directory
If it doesn't exist, you'll get:
-bash: cd: /path/to/directory: No such file or directory
Create the directory, or correct the path in DeployHQ.
Shared hosting note: Some hosting providers jail accounts to a subdirectory, preventing access to the server's root. In these cases, log in with the DeployHQ user to see which directory you land in, then use a relative path from there. See our guide on using DeployHQ with shared hosting providers for more details.
The user doesn't have write permission
If the directory exists but the user can't write to it, check the current permissions:
ls -ld /var/www/my-site
If you see output like this, only the root user can write:
drwxr-xr-x 4 root root 1462 11 Apr 16:27 my-site
Fix with chown (change directory ownership):
chown deployuser:deployuser /var/www/my-site
Fix with chmod (change permissions):
chmod 755 /var/www/my-site
This gives full read, write, and execute access to the owner, and read/execute to everyone else. For a detailed explanation of Linux file permissions, see this file permissions reference.
FTP passive mode issues
When using FTP, some servers require passive (PASV) mode for data connections. If your connection succeeds but file operations fail, enable the Use passive (PASV) mode option in your server settings within DeployHQ.
This is especially common with servers behind NAT or cloud hosting providers where the default active FTP mode can't establish the data channel.
Related: If FTP is causing persistent issues, consider switching to SFTP. See how to deploy to your server using SSH/SFTP for a step-by-step setup guide.
Still stuck?
If none of these steps resolve your issue:
- Check the common deployment errors section in our documentation
- Try the DeployHQ AI troubleshooting helper for automated diagnosis of deployment error logs
- Drop us an email at support@deployhq.com — we're happy to help you get connected
You can also follow us on Twitter/X for tips and updates.