Troubleshooting SFTP

SFTP connection issues are typically caused by firewalls or incorrect settings in SFTP software. The steps below will help you resolve these issues.

We often encounter resistance from customers who are unwilling to invest in troubleshooting their client or firewall because a previous connection may have worked.

In our experience, the change that caused the problem is usually on the customer's side, and we would appreciate it if you could go through and verify all of the following things before asking us for further assistance.

Check for Firewall Issues

During the majority of support calls pertaining to SFTP, the primary underlying factor is typically associated with the corporate or network firewall of the customer or customer counterparty.

SFTP is a frequently restricted protocol by firewalls. In many cases, modifications to firewalls can inadvertently introduce new complications that were previously non-existent.

Have you manually whitelisted any IP addresses anywhere?

If so, you need to all of the appropriate IPs are whitelisted, not just some of them.

See if you need to ask for an IP whitelist.

If you have not whitelisted IP addresses, maybe your firewall administrator requires an explicit whitelist for SFTP traffic. Please submit a request to your network or firewall administrator to allow SFTP port 22 traffic to all of the IP addresses used by your server.

Connection Settings in Your SFTP App

The following connection settings are the most common issues related to SFTP. Please double-check all of the following.

Hostname

The hostname should be set to the domain for your site. Connecting by specifying an IP address may sometimes work, and we do have customers doing this for specific reasons, but it is not officially supported and we are unable to proceed with helping you troubleshoot if you are doing this.

Port

By default, you should be using port 22. The default SSH/SFTP port of 22 is blocked or interfered with by many corporate firewalls.

Timeout

If supported in your app, please increase the connection timeout value to 60 seconds.

Retry Logic

If supported in your app, have your app attempt three connection retries at 10-second intervals. This will allow failed connections contacting one server to retry the connection via a different server.

Keepalives

SmartFile will time out SFTP sessions that have been idle for 120 seconds. This is to prevent unused sessions from being left open and using server resources. Such idle timeouts are normal, and most SFTP apps handle them without issue, but there are some apps that may not handle these timeouts gracefully. To prevent these idle timeouts, many apps offer a "keepalive" setting. Many SFTP apps will complete transfers in progress and then will connect again upon the user issuing another command. If your app aborts a transfer or errors out due to the idle timeout message, you can implement keepalives (either null packets or dummy commands) every 100 seconds to maintain the SFTP connection and avoid the timeout messages.

Ciphers

Your SFTP app and SmartFile will only connect if both sides agree to use a secure cipher. Insecure ciphers can be rejected by either side. Make sure that your SFTP app uses a supported secure cipher.

Please check the documentation for your SFTP app to find out how to configure ciphers for your connection.

Configuration on SmartFile That May be Relevant

If you have confirmed all of the above, here are some remaining things that have caused SFTP issues for some of our customers.

Verify that the username is enabled, and that the username and password are correct. Click the Users icon in the left menu, users will have a green check if enabled and a red X if disabled. To enable a user, select the user that is disabled and click Enable/Disable.

Authentication or Invalid Username/Password Failure Messages

The SFTP protocol has a "gotcha" that often confuses SFTP users when trying to troubleshoot authentication issues. The protocol uses integers internally to communicate authentication failure codes and does not even allow services (such as SmartFile) to send detailed error messages that relate to authentication.

This is in contrast to nearly every other protocol, such as our API, FTP, web, etc., which all provide detailed messages that explain login failures.

Many SFTP client software will simply plug in a "default" message about authentication failure or invalid username/password when they experience any sort of authentication failure. We recommend using your SmartFile site's activity logs to determine the real reason for the failure.