There are a number of issues you might run into when adding a new server to your [DeployHQ](https://www.deployhq.com) project. In this guide, we'll walk through how [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com) always runs through the same validation steps. ## Step 1: Connection test First, [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com) can authenticate with the credentials you've provided, whether that's a username and password or an [SSH key](https://www.deployhq.com/blog/5-ways-to-create-ssh-keys-from-the-command-line-for-deployhq) ## Step 2: Deployment directory and file permission test Once the connection succeeds, [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com) 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](https://www.deployhq.com) 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](https://www.deployhq.com/support/firewall). 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](https://www.deployhq.com), 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](https://www.deployhq.com) 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](https://www.deployhq.com). 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](https://www.deployhq.com/blog/what-are-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: 1. **Copy the correct public key** : Each [DeployHQ](https://www.deployhq.com) project has a unique SSH public key. Copy it from your project's server configuration page and add it to `~/.ssh/authorized_keys` on your server. 2. **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. 1. **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-rsa` or `ssh-ed25519`. > **Related** : For a deeper dive into SSH key issues, see our [guide to creating and managing SSH keys](https://www.deployhq.com/blog/5-ways-to-create-ssh-keys-from-the-command-line-for-deployhq). ### Password authentication For password-based authentication: 1. Double-check that the username and password are entered correctly in [DeployHQ](https://www.deployhq.com) — copy-paste errors with trailing spaces are common 2. Try logging into your server from a local terminal or FTP client with the same credentials 3. Check that password authentication is enabled in your server's SSH configuration (`PasswordAuthentication yes` in `/etc/ssh/sshd_config`) * * * ## Fixing directory and file permission errors After authentication, [DeployHQ](https://www.deployhq.com) 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](https://www.deployhq.com). **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](https://www.deployhq.com) user to see which directory you land in, then use a relative path from there. See our guide on [using](https://www.deployhq.com/blog/using-deployhq-with-shared-hosting-providers)[DeployHQ](https://www.deployhq.com) 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](https://ss64.com/bash/chmod.html). * * * ## 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](https://www.deployhq.com). 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](https://www.deployhq.com/blog/how-to-deploy-to-your-server-using-ssh-sftp-and-git-with-deployhq) for a step-by-step setup guide. * * * ## Still stuck? If none of these steps resolve your issue: 1. Check the [common deployment errors](https://www.deployhq.com/support/common-deployment-errors) section in our documentation 2. Try the [DeployHQ AI troubleshooting helper](https://www.deployhq.com/blog/introducing-the-deployhq-ai-helper-faster-troubleshooting-for-deployment-errors) for automated diagnosis of deployment error logs 3. Drop us an email at [support@deployhq.com](mailto:support@deployhq.com) — we're happy to help you get connected You can also follow us on [Twitter/X](https://x.com/deployhq) for tips and updates.