Troubleshooting Outbound SFTP

Outbound SFTP connections can be interrupted by a variety of issues. Some are fixed by changing configuration settings in your Files.com site. Others must be addressed in the configuration of the remote SFTP system or its firewall.

Connection errors appear when you create or edit the Remote Server. Files.com records errors for individual file and folder operations in the Outbound Connections log. Some errors begin with a bracketed prefix that identifies the Remote Server by its ID and internal name. Correlate the time, path, and operation with the remote server’s records. A connection test establishes reachability and authentication; a successful file operation establishes access only for that operation and path.

Hostname Is Invalid

The error Hostname is invalid means Files.com cannot resolve the hostname of the remote SFTP server.

Enter the hostname without a protocol or path. Use a hostname resolvable from the selected connection route. A public connection needs public reachability; Agent routing resolves and reaches the service from the Agent's network.

Incorrect Port for SFTP

The error Ports 21 and 990 are typically used for FTP, not SFTP flags a port conventionally used by FTP(S). If the connection information you were given specifies ports 21 or 990, confirm whether the remote server uses FTP(S) instead of SFTP. If it uses FTP(S), add a remote server using the FTP protocol.

Connection Times Out

The error Timeout establishing ssh connection means the SSH connection did not finish establishing within the allowed time. If the remote server logs connection attempts, check for the failed connection: no corresponding attempt points toward the host, port, route, or network path; an accepted attempt that stalls calls for investigation of the server’s response and load.

Firewalls or other restrictions on the remote server can require an IP address to be allowlisted. Verify that connections from Files.com IP addresses are allowed by the remote SFTP server. Verify the IP addresses that are being used for connections from your Files.com site, and confirm that these IP addresses are not blocked by any firewalls.

When intermittent network issues exist between Files.com and the remote server, SFTP commands or their responses can fail to occur within the time allowed by the SFTP protocol.

When the remote SFTP server changes something, such as the authentication method or the SFTP port, SFTP connections from Files.com can time out because they are trying to connect using outdated information.

A slow response can come from server load as well as the network path. Distinguish connection establishment from a command or transfer that stalls after authentication, and compare the failed stage with the remote service's records. A timeout alone does not prove that the remote server exhausted its CPU or memory.

SFTP servers can implement rate limits that cap the number of times the server can be connected to within a specified duration. Dedicated addresses can separate your connection from shared-address contention, but do not override the remote service's own limits.

Resolve any network issues and confirm that the remote SFTP server can support the connection load being sent to it from Files.com. Confirm that combined workloads from all Syncs, Remote Mounts, and Automations to the remote server stay within its operational limits.

Authentication Failed

The error Authentication failed - Verify credentials (password) and also confirm that Files.com IPs are whitelisted. means the remote SFTP server rejected the credentials that Files.com presented. The text in parentheses names the authentication method configured for the connection. A connection that authenticates with a private key shows (private key).

Check that the username, password or private key, and authentication method match what the remote SFTP server requires. Some SFTP servers also reject connections from IP addresses that have not been allowlisted. Confirm that the remote SFTP server allows connections from Files.com IP addresses.

Server Refused the Connection

The error Connection failed: The server refused the connection during authentication means the remote server ended the connection before authentication completed.

This occurs when the service at the configured hostname and port is not an SFTP server. For example, connecting to an FTP(S) service on port 990 produces this error.

This also occurs when the remote SFTP server and Files.com cannot agree on the SSH algorithms used for the connection. Connections to a remote SFTP server use the algorithm cipher agreed upon by both Files.com and the remote system. Files.com presents its supported ciphers to the remote SFTP server. SSH negotiation selects mutually supported algorithms for key exchange, host keys, encryption, and message authentication. Contact the administrator of the remote SFTP server to determine which SSH algorithm ciphers that system supports.

Some SFTP servers allow customization or are implemented in a non-standard way. Connectivity to non-standard SFTP servers is not always successful.

Host Key Mismatch

The error Host key mismatch means the host key presented by the remote SFTP server does not match the Server Host Key configured for the Remote Server. This occurs when the remote server's host key has changed.

If Server Host Key contains an OpenSSH host certificate, renewal can cause this error even when its underlying public key stays the same. Files.com compares the complete pinned certificate. Certificate expiration alone does not end the pin.

Obtain and verify the current host key or certificate with the administrator of the remote SFTP server before updating Server Host Key. To avoid repinning after certificate renewals, confirm that the server offers its plain host key and configure that verified plain key as the pin.

Permissions Error

The error Permissions Error means the user account that Files.com uses to connect does not have permission to perform the attempted operation on the remote SFTP server.

Files.com records the failed operation in the Outbound Connections log along with the operation type and error message. Ask the administrator of the remote SFTP server to check the configured account’s rights on that path and grant the permissions the operation needs. Preserve the account and route while testing so the result can be compared with the failure.

One case is worth checking first. A delete recorded against a path that an Automation was only moving or copying into is part of an overwrite in v1 or v2. Files.com deletes the existing file before writing the new one, so the account needs delete rights on the destination folder.

A Sync writes over the existing file instead of deleting it, which makes it the alternative when the server's owner will not grant delete rights. Test a Sync against that server first, because an SFTP server that refuses to replace a file in place sends Sync back to deleting and recreating. Use an isolated destination and a disposable file for that replacement test, with source deletion off. A new-file upload alone does not test replacement. Confirm both the recorded operation and the remote file’s contents before applying the correction to production.