An SFTP connection must reach the server, negotiate encryption, and authenticate before it can transfer files. Start with the stage named in the client's error. A connection timeout, an authentication error, and a denied file operation need different checks.

The Connection Times Out or Cannot Reach the Server

Confirm that the client uses the correct site hostname or custom domain and port 22 or 3022. The client's network or corporate firewall may block SFTP even when ordinary web traffic works. If port 22 is blocked, test port 3022 and coordinate access with the network administrator.

If a firewall uses an IP whitelist, confirm that it includes every destination address required for the hostname, rather than just one server address. Connection Settings explains the addresses for custom domains and standard Files.com hostnames.

The Client Cannot Negotiate Encryption

The client and server must agree on a supported cipher. Confirm that the client supports SSH-2 and the enabled algorithms. Cipher troubleshooting covers this stage separately from credentials and folder access.

Authentication Errors

SFTP clients often show a generic authentication error or an invalid username/password message for several different causes. Use your site's API Logs to investigate the failed session request from the SFTP interface. Login failures do not appear in History Logs.

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, login attempt 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.

If an SFTP login works from a workstation but fails from a hosted integration, check the integration's own network path and public source address. The successful workstation login does not verify those conditions. Shared Cloud Environments explains how shared or changing cloud addresses can affect connections and the options for controlling outbound addresses.

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.

Check the user's actual folder permissions and root and home folder settings. Permission values displayed by a Unix-style client do not represent the user's Files.com access. Folders & Permissions explains those distinctions and the behavior of missing upload folders.

Moves and renames can run in the background, so a successful response does not always mean the destination is visible immediately.

An Upload Is Incomplete or Cannot Resume

Check the Preserve Partial SFTP Uploads After Disconnects setting and whether the client explicitly closed the file before disconnecting. A resumable upload also needs its partial file to remain at the original location. Uploads explains the setting, completion messages, and temporary-filename handling.

Troubleshooting