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 Files.com) 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 apps will simply plug in a "default" message about authentication failure or invalid username/password when they experience any sort of authentication failure, and the exact wording varies by app. We recommend using your Files.com site's API Logs to determine the real reason for the failure. Login failures do not appear in History Logs. They are recorded only in the API Logs, as a failed session request from the SFTP interface.

A failed SFTP login is recorded in the API Logs with the Error Type not-authenticated/invalid-username-or-password. Add the Error Type and Status columns to the API Logs to see this value. The same error type covers every kind of failed authentication, including an incorrect password and an SFTP (SSH) key that does not match a key in your site.

Common causes of failure include expired passwords, required password change, brute force protection, IP restrictions, 2FA restrictions, and geographic restrictions. The Login Failures page lists every reason a login can fail.

A login that keeps failing, even with the correct password or key, often traces back to a setting on the user's account.

User Account Settings

Verify that the username is enabled. Edit the user and confirm that the Account Enabled setting is turned on. Confirm that the Authentication Method is not set to None (Use SSH or API keys). When set to None, a user account can only authenticate by using an API key or an SSH/SFTP key.

SFTP Protocol Access

The user might have SFTP disabled in their settings. Edit the user and check that SFTP is allowed in their Protocol Access settings.

Require Password Change

If the user account has been configured to Require password change on next login, SFTP login will not succeed until the password has been changed. Ask the user to access Files.com through the web interface and complete the password change before attempting a login via SFTP.

Two Factor Authentication (2FA)

If the user has Two Factor Authentication (2FA) enabled, only certain 2FA methods work with SFTP, and using one costs you throughput. Disable any parallelism in your SFTP app, because each 2FA code authenticates one connection at a time. Elsewhere we recommend maxing out the available parallelism in your app for performance, and 2FA is the case where you cannot use it.

Consider whether this connection needs an SFTP client at all. The Files.com Desktop App and CLI App answer the second factor once at login and keep parallel transfers, and automated transfers belong on an SFTP/SSH key or an API key rather than 2FA.

IP Whitelist

If your site or user is subject to an IP Whitelist, the user must access the site using one of the whitelisted IPs from either list. Check your IP whitelists to confirm that the IP address making SFTP connections is allowed.

Eliminate SFTP as the Sole Cause

If a user has problems logging in via SFTP, have them attempt to log in using the Files.com web interface. If the issue persists there, that eliminates SFTP as the cause.

Several failed login entries in quick succession from one user, followed by a successful login, can indicate either a legitimate mistake or a false alarm. A user might be trying to log in using an incorrect SFTP (SSH) key. Contact the user and verify that the key being used matches an existing SFTP (SSH) key in your Files.com site.

Many SFTP apps automatically attempt to log in using all their known SFTP (SSH) keys before presenting the user with a login prompt. These apps hold keys in an SSH agent or in configured key files, and the app cycles through them one by one, trying each one before falling back to a login prompt. Each of those automatic attempts shows up in the log as a failed login, even though the user then logs in successfully. The log entries are accurate, and the failures themselves are not a problem. You can contact the user and ask them to remove unneeded keys from their SSH agent or app configuration. The same keys are often shared by multiple SFTP and SSH apps, so removing keys is not always practical for a user who actively works with several SFTP or SSH sites.

When a login attempt uses a username that does not exist on your site, Files.com closes the connection before authentication and writes nothing to the API Logs. When a user reports a failed login and the API Logs show no matching entry, confirm the exact username with the user. A typo, or a username that belongs to a different site, is the usual cause.

Troubleshooting SFTP Login Failures