How to read DeployHQ's transfer error messages

When DeployHQ cannot connect to your server or a file transfer fails, the error message in your deployment log follows a consistent three-part format:

[What happened] + [Why] + [What to try]

This article explains how to read each part and what to do when you see common error categories.

The three-part format

Every transfer error message starts with a short statement of what went wrong, followed by a likely cause, and ends with a concrete suggestion. For example, instead of a raw library message like:

Net::SSH::ConnectionTimeout: Net::SSH::ConnectionTimeout

You will see:

Connection to 203.0.113.10:22 timed out. The server did not respond within 30 seconds, which usually means a firewall is dropping the connection or the server is down. Check that the host and port are correct and that DeployHQ's IP addresses are allowed through any firewalls.

The three parts are intentionally split so each one helps a different question:

• What happened -- enough detail to identify the failure in your deployment log without re-reading the stack trace
• Why -- the most likely cause based on the error category, in plain language
• What to try -- the first thing to check, usually a specific setting or action

Common categories

Connection timeouts

Connection to host:port timed out. The server did not respond within the configured timeout, which usually means a firewall is dropping the connection or the server is down. Check that the host and port are correct and that DeployHQ's IP addresses are allowed through any firewalls.

Most often caused by firewall rules. See Connection errors for a list of DeployHQ's outbound IP addresses to allow.

Authentication failures

Authentication failed for user deploy on host. The username or SSH key is rejected by the server. Verify the username and copy DeployHQ's public key from your server settings into the server's ~/.ssh/authorized_keys file.

If you are using SSH, this almost always means the public key on your DeployHQ server settings is not present (or is malformed) in the target user's authorized_keys. See SSH public key authentication errors.

For FTPS, see FTPS authentication errors.

Host not found

Could not resolve host. The server's DNS name did not return an IP address, which usually means the hostname is misspelled or the DNS record has been removed. Verify the host setting on your server configuration.

A DNS failure usually points at a typo in the host field. Double-check the exact spelling, including any trailing period or subdomain.

TLS / SSL negotiation failures (FTPS, SFTP)

Could not establish a secure connection to host. The server requires a TLS version that the selected configuration does not support, or its certificate could not be validated. Try selecting Auto-negotiate as the TLS version, or check your server administrator for the required version.

For FTPS specifically, DeployHQ supports TLS 1.0 through TLS 1.3, plus an Auto-negotiate option that lets your server pick the highest mutually supported version. See FTPS for full TLS configuration.

Permission denied during transfer

Permission denied uploading path/to/file on host. The deploy user does not have write access to the deployment path. Check the directory permissions and the user's group membership on the server.

This appears mid-deployment, not at connection time. The connection worked, but the deploy user cannot write to the deployment directory. Fix with chown / chmod on the deployment path, or by changing the deploy user.

Disk full

Could not write path/to/file on host: no space left on device. The target server has run out of disk space. Free up space on the deployment volume and retry the deployment.

The deploy halts cleanly when disk is exhausted, leaving previously transferred files in place. Free space and retry.

When error messages still look raw

If you see a long stack trace or an error message that does not match the three-part format, that error category has not yet been rewritten. You can still find context for these in the parent Common Server Errors section, which collects troubleshooting guides for the specific underlying libraries (Net::SSH, Net::FTP, Aws::S3, and so on).

If you can reproduce a raw-looking error and would like clearer messaging, send us the deployment log -- we are continuously rewriting error messages as we see them in the wild.