Skip to main content

Troubleshooting

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. The errors below identify client compatibility problems at this stage, before credentials and folder access are checked.

SFTP Connection Failed with "DHG1_KEX_FALLBACK" Cipher

The Diffie-Hellman key exchange method implements a fallback for situations where the client and server cannot agree on a cipher strength. A fallback to a weaker cipher requires agreement from both the server and the client. Some clients contain a bug that causes them to ignore the server when it prohibits a fallback, and they attempt to connect using the weaker fallback cipher anyway.

For example, the cipher diffie-hellman-group-exchange-sha256 aes128-ctr hmac-sha1 DHG1_KEX_FALLBACK indicates that the server requested the use of a strong cipher (diffie-hellman-group-exchange-sha256 aes128-ctr hmac-sha1) but the client instead attempted to connect with a weaker fallback cipher (note the DHG1_KEX_FALLBACK part of the cipher string.)

Upgrade the client to a version that honors the server's refusal, or ask its vendor for a build that does.

Enabling insecure ciphers also lets the connection succeed, because it permits the weaker fallback the client requests. The setting is sitewide, so you would weaken every connection to your site to accommodate one client's bug. Treat it as a temporary measure while the client is replaced.

Failed SSH Key Exchange or Bad server public DH value error using Ipswitch WS_FTP or MoveIt

WS_FTP versions prior to 12.6 and MoveIt versions prior to 9.1.0.3.0 do not support the ciphers needed for Files.com to operate securely.

If these apps have been upgraded and key exchange errors persist, there is a known issue with upgrading previous versions of WS_FTP Professional to 12.6 where the ssh-algos.txt file is not updated with the diffie-hellman-group-exchange-sha256 ssh-kex.

To resolve this, manually add that entry to the ssh-algos.txt file located at C:\Users\<user>\AppData\Roaming\Ipswitch\WS_FTP.

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 explains which attempts can be associated with your site and where they are recorded.

Login Fails with an Authentication Error

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

Confirm that the user's Account Enabled setting is turned on, then match the client's credential to the account's authentication method. None (Use SSH or API keys) allows SSH/SFTP keys and API keys while disabling password authentication.

For an SSH-key login, confirm that the matching public key is registered on that account. Password and SFTP/SSH key (SFTP only) requires both credentials. For an API-key login, the client must use the API key's login name, rather than the account's ordinary username.

SFTP Protocol Access

Confirm that SFTP is enabled for the site and allowed by the user's effective Protocol Access. A Group can grant access even when the user's own SFTP setting is off. When the site manages protocol access through Groups, the user needs membership in a Group that allows SFTP.

Require Password Change

When Require password change on next login applies to a Password account, it blocks SFTP login with the user's username, including an SSH-key login. The user must complete the password change through the web interface before reconnecting. API-key authentication is independent of this password requirement.

Two Factor Authentication (2FA)

If the connection requires Files.com Two Factor Authentication (2FA), only certain 2FA methods work with SFTP. Your SFTP app's parallel connections and later reconnects can reuse the same password and appended code from the same source IP address to the same Files.com server address, within the first sign-in's session limits.

If the first connection succeeds but another rejects that code, check whether it reaches a different server or uses a different source address or SSH connection settings. A new connection also needs a fresh code after the reuse period ends. Opening another connection does not restart that period, and an unchanged hostname can still resolve to a different server address.

An SSH key alone cannot satisfy Files.com-managed 2FA. A human account with that requirement needs the appropriate protocol bypass for key-only SFTP. API-key logins do not involve 2FA. Unattended transfers use separate machine accounts with Shared/bot user enabled, as in receiving files from a partner system.

Consider whether a person 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.

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

For a person whose account supports password or SSO sign-in and has web access, a web login can help check that sign-in method. It does not test the SSH key or API key used by an SFTP connection. Accounts set to None or Password and SFTP/SSH key (SFTP only) have no password or SSO web sign-in to use for this comparison; investigate the actual SFTP credential and connection instead.

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.

A Burst of Failed Logins Followed by a Successful Login

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.

A Failed Login Does Not Appear in the API Logs

Confirm the exact username and destination with the user. An unknown username on a shared Files.com address can leave no entry because the attempt cannot be associated with your site. A dedicated site address identifies the site even when the username is unknown. The failed login records guidance explains that distinction; also compare the attempt's time and public source IP address with your search filters.

Login Works but Folders or File Operations Are Unexpected

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.