Troubleshooting SFTP User Connection Error in Debian 11

Resolving SFTP user connection errors in Debian 11 typically involves verifying that the sshd service is running, ensuring the correct subsystem is configured in /etc/ssh/sshd_config, and checking file permissions for the user’s home directory. Most failures stem from misconfigured paths or restrictive ownership settings that prevent the internal-sftp subsystem from executing.

Verifying the SSH Daemon Status

The first step in troubleshooting any remote access issue is confirming that the underlying service is active and listening on the expected port. On Debian 11, the Secure Shell daemon is managed by systemd, and its status can be checked using standard diagnostic commands. It is critical to use the correct service name, which is sshd, not ssh. Using the wrong name will result in a "Unit ssh.service not found" error, delaying your diagnosis. Run the following command to check the current state of the daemon:

systemctl status sshd

If the service is inactive or failed, you should see red text indicating the error reason. Common reasons include configuration syntax errors or port conflicts. If the service is active (running), proceed to verify that it is listening on port 22 or your custom port. You can use ss or netstat to confirm:

ss -tlnp | grep sshd

Look for a line showing LISTEN on :22 or your designated port. If nothing appears, the daemon may not have started successfully despite the status command showing otherwise. In such cases, check the journal logs for immediate feedback:

journalctl -u sshd -e

This log output often reveals why the process terminated immediately after starting, such as a duplicate port binding or an invalid key file.

Configuring the Internal SFTP Subsystem

Debian 11 uses OpenSSH, which includes a built-in SFTP server called sftp-server (often referred to as internal-sftp). This subsystem runs within the SSH process itself, eliminating the need for external binaries like vsftpd or proftpd. Misconfiguration here is the most common cause of "Subsystem request failed" errors. Open the main configuration file with a text editor:

sudo nano /etc/ssh/sshd_config

Locate the line defining the subsystem. It should look like this:

Subsystem sftp internal-sftp

Ensure there are no typos in internal-sftp. If you see internal-sftp commented out with a hash (#), remove the hash. If you previously installed third-party FTP servers, ensure they are not conflicting by commenting out their subsystem lines. After making changes, test the configuration for syntax errors before restarting:

sudo sshd -t

If this command returns no output, your configuration is syntactically valid. If it reports an error, fix the line indicated and try again. Once validated, restart the service:

sudo systemctl restart sshd

For more details on similar subsystem failures, you might find our guide on Troubleshooting SFTP Connection: Subsystem Request Failed helpful if the issue persists after these checks.

Restricting Users to SFTP Only

To enhance security, you may want to restrict specific users to SFTP only, preventing them from gaining shell access. This is achieved using Match blocks in sshd_config. Add the following at the end of the file:

Match User username
    ChrootDirectory /home/username
    ForceCommand internal-sftp
    AllowTcpForwarding no
    X11Forwarding no

Replace username with the actual account name. The ChrootDirectory must point to a directory owned by root and not writable by the user. This setup ensures that when the user logs in, they are dropped into their home directory and cannot navigate above it.

Checking File Permissions and Ownership

Even with correct configuration, connection errors occur if the user lacks permission to access their home directory or execute the SFTP subsystem. Debian enforces strict ownership rules for secure remote access. The user’s home directory must be owned by root and not group-writable if you are using ChrootDirectory. Verify the permissions:

ls -ld /home/username

You should see something like drwxr-xr-x root root. If the owner is the user themselves, the chroot will fail silently or produce permission denied errors during connection. To fix this:

sudo chown root:root /home/username
sudo chmod 755 /home/username

If the user needs to upload files, create a subdirectory within their home that they own:

sudo mkdir /home/username/uploads
sudo chown username:username /home/username/uploads
sudo chmod 755 /home/username/uploads

Users can then upload files to the uploads folder while remaining confined to the chrooted environment. This structure balances security with usability.

Firewall and Network Considerations

Debian 11 often comes with ufw (Uncomplicated Firewall) enabled by default. If the firewall is active, it may block incoming connections on port 22. Check the status with:

sudo ufw status

If it shows active, ensure that SSH traffic is allowed:

sudo ufw allow ssh

Or specify the port explicitly if you are using a non-standard port:

sudo ufw allow 2222/tcp

After allowing traffic, attempt the connection again. If you still experience timeouts, verify that your network provider or cloud hosting panel does not block inbound ports.

Testing the Connection Locally

Before testing from a remote machine, test locally to isolate network issues. Run:

ssh -v username@localhost

The -v flag enables verbose output, showing each step of the authentication and subsystem negotiation. Look for the line Entering interactive session or Authentication succeeded. If it fails here, the problem is definitely local configuration. If it succeeds locally but fails remotely, the issue is likely firewall-related or DNS resolution.

Frequently Asked Questions

Why does my SFTP connection time out even though SSH works?

A timeout usually indicates a network block rather than an authentication failure. Check if ufw or your cloud provider’s security group allows inbound TCP traffic on port 22. Additionally, verify that your ISP or corporate firewall is not filtering SFTP-specific packets.

Can I use a different SFTP server instead of internal-sftp?

Yes, you can install standalone servers like vsftpd or proftpd, but this requires additional configuration and separate services. For most Debian 11 setups, sticking with internal-sftp is simpler and more secure as it integrates directly with SSH authentication. See our article on ProFTPD SFTP problems if you prefer managing a separate daemon.

What causes the 'Permission denied' error after successful login?

This error almost always stems from incorrect ownership of the ChrootDirectory. The directory specified in ChrootDirectory must be owned by root and not writable by the user. Ensure you have set chown root:root on the home directory and created a writable subdirectory for the user.

How do I enable logging for SFTP failures?

Increase the logging level in /etc/ssh/sshd_config by setting LogLevel VERBOSE. Then restart the sshd service. Check /var/log/auth.log for detailed messages related to SFTP subsystem requests and authentication attempts.

Is it safe to disable password authentication for SFTP?

It is highly recommended to disable password authentication and use key-based auth instead. This prevents brute-force attacks. Configure PasswordAuthentication no in sshd_config and ensure your user has their public key added to ~/.ssh/authorized_keys.