SFTP authentication failures typically stem from incorrect credentials, misconfigured server permissions, or SSH key mismatches. To resolve this, verify your username and password, check the
~/.ssh/authorized_keys file on the remote host, and ensure the correct port is being used. This guide details the systematic steps to diagnose and fix these common connection errors across Linux, macOS, and Windows environments.
Verify Basic Credentials and Connection Parameters
The most frequent cause of an "Authentication Failed" error is a simple typo in the username or password. Before diving into complex configurations, ensure that you are connecting to the correct host and using the standard SFTP port, which is 22 by default. If your server uses a non-standard port, you must specify it explicitly in your command line or client settings.
When using the command-line interface, the syntax is
sftp username@hostname. If you encounter an immediate rejection, try logging in via SSH first with
ssh username@hostname -p 22. SSH provides more verbose output regarding authentication methods. If SSH works but SFTP fails, the issue likely lies within the SFTP subsystem configuration rather than your credentials. Conversely, if both fail, the problem is almost certainly related to user permissions or account status.
Always double-check for hidden characters in your password, especially if you copied and pasted it from another source. Special characters may need escaping depending on the shell you are using. Additionally, confirm that the user account has not been locked due to previous failed login attempts, a security feature common in modern Linux distributions.
Check SSH Key Configuration and Permissions
If you are using public-key authentication instead of passwords, the private key must be accessible and correctly formatted. The SSH client looks for keys in
~/.ssh/id_rsa,
~/.ssh/id_ed25519, or other specified locations. You can list available keys with
ls -la ~/.ssh/. Ensure that the private key file has restrictive permissions, typically set to 600 (
chmod 600 ~/.ssh/id_rsa). If the permissions are too open, the SSH client will ignore the key for security reasons.
On the server side, the corresponding public key must be present in the
~/.ssh/authorized_keys file for the target user. Verify that the
.ssh directory and the
authorized_keys file have the correct ownership and permissions. The
.ssh folder should be 700, and
authorized_keys should be 600. Incorrect ownership, such as the files belonging to root instead of the specific user, will prevent authentication.
Sometimes, the SSH agent does not load the key automatically. You can manually add the key using
ssh-add ~/.ssh/id_rsa. Check the agent's loaded keys with
ssh-add -l. If the key is missing, the agent cannot use it for authentication, leading to a failure even if the key itself is valid.
Inspect Server-Side Logs and Configuration
When local checks pass, the issue often resides on the server. System logs provide critical insights into why the connection was rejected. On Linux systems, check
/var/log/auth.log or
/var/log/secure using
sudo tail -f /var/log/auth.log. Look for entries related to
sshd that mention "authentication failure" or "invalid user." These logs will indicate whether the server received the request and why it denied access.
Review the main SSH configuration file, usually located at
/etc/ssh/sshd_config. Ensure that
PubkeyAuthentication yes and
PasswordAuthentication yes are enabled if you intend to use those methods. Some servers disable password authentication for security, requiring key-based login exclusively. If you recently changed the configuration, restart the SSH service with
sudo systemctl restart sshd to apply changes.
Also, verify that the SFTP subsystem is correctly defined in the configuration. It should include a line like
Subsystem sftp /usr/lib/openssh/sftp-server. If this line is commented out or points to an incorrect path, SFTP connections will fail even if SSH works. In some older versions, the subsystem might point to an external binary, so ensure that binary exists and is executable.
Firewall and Network Interference
While less common for authentication errors, network issues can sometimes manifest as timeouts that look like failures. Ensure that no firewall rules are blocking port 22 or interfering with the TCP handshake. Use
telnet hostname 22 or
nc -zv hostname 22 to test basic connectivity. If the connection hangs, a firewall is likely dropping packets.
Some corporate networks or ISPs may block or throttle SSH traffic. If you are behind a proxy or using a VPN, ensure that SFTP traffic is allowed through these intermediaries. Testing from a different network can help isolate whether the issue is local to your current environment.
Transfer Files Using WinSCP instead of SFTP with SCP Protocol offers an alternative approach if command-line tools remain problematic. GUI clients like WinSCP often provide detailed error messages that can clarify ambiguous authentication issues. They also allow you to save credentials securely, reducing the chance of input errors during repeated connections.
Common Pitfalls and Advanced Diagnostics
One subtle issue is the difference between SCP and SFTP protocols. While they share the same underlying SSH transport, they use different subsystems. If you are using an SCP client to connect to an SFTP server, it may fail. Ensure your client matches the protocol expected by the server. Similarly, some servers restrict SFTP access to specific groups. Check the
AllowGroups or
DenyUsers directives in
sshd_config to ensure your user is permitted.
For advanced debugging, run the SSH client with verbose mode:
ssh -v username@hostname. This outputs detailed information about the negotiation process, including which authentication methods are offered and accepted. Analyzing this output can pinpoint exactly where the handshake breaks down.
If you suspect a corrupted key, regenerate it and update the server's
authorized_keys file. Always backup existing keys before making changes. Remember that changing authentication methods requires updating both client and server configurations consistently.
Frequently Asked Questions
Why does SFTP fail while SSH works?
This indicates a problem with the SFTP subsystem configuration on the server rather than your credentials. Check the
Subsystem sftp line in
/etc/ssh/sshd_config to ensure it points to the correct binary. Restarting the SSH service after any configuration change is also necessary.
How do I reset my SFTP password if I forgot it?
You cannot reset the password remotely without admin access. Contact your system administrator to reset the account password or unlock the account. If you have sudo privileges, you can use the
passwd command to change it yourself.
Can I use the same key for multiple users?
It is technically possible but highly discouraged for security reasons. Each user should have their own unique key pair. If you must share access, consider using group permissions or sudoers files instead of sharing private keys.
What causes permission denied errors after authentication succeeds?
This usually means the user lacks read/write access to the target directory. Check the ownership and permissions of the home directory and subfolders using
ls -la. Ensure the user owns the files or belongs to a group with appropriate access rights.
Is it safe to disable password authentication?
Disabling password authentication improves security by preventing brute-force attacks. However, ensure you have reliable key-based access set up first. If you lose your key, recovery becomes difficult without physical or console access to the server.