The "subsystem request failed" error in SFTP typically indicates that the SSH server cannot locate or execute the SFTP subsystem binary, often due to an incorrect path in the SSH configuration file. This issue usually stems from misconfigured
Subsystem directives in
/etc/ssh/sshd_config or insufficient permissions for the user attempting the connection. Resolving this requires verifying the server-side configuration and ensuring the correct internal-sftp or external binary is referenced.
Understanding the Error Message
When you attempt to connect using a command like
sftp user@host, the client initiates an SSH session and then requests a specific subsystem known as "sftp". If the server responds with "subsystem request failed on channel 0", it means the SSH daemon (
sshd) accepted the connection but failed to start the file transfer service. This is distinct from authentication failures or network timeouts; the handshake was successful, but the service layer could not initialize. Common variations of this error include "channel 0 open failed" or "open failed: administratively prohibited", which may point to different underlying causes such as chroot restrictions or permission denials.
Verifying the SSH Configuration File
The most common cause is an incorrect or missing directive in the
/etc/ssh/sshd_config file on the server. You must ensure that the Subsystem line points to the correct executable. In modern OpenSSH installations, the SFTP functionality is often handled by an internal subsystem rather than an external binary. The standard configuration should look like this:
Subsystem sftp internal-sftp
If your configuration specifies an external path, such as
/usr/libexec/openssh/sftp-server, verify that this file exists and is executable. To check if the binary exists, run
ls -l /usr/libexec/openssh/sftp-server or use
which sftp-server. If the path is wrong, update the
Subsystem line accordingly. After making changes, you must restart the SSH service using
sudo systemctl restart sshd for the changes to take effect. For Debian-based systems, refer to our guide on
Troubleshooting SFTP User Connection Error in Debian 11 for distribution-specific nuances.
Checking Chroot Directory Permissions
If you are using a ChrootDirectory to restrict users to a specific folder, strict permission rules apply. The directory specified in the ChrootDirectory directive and all its parent directories up to the root must be owned by
root and not writable by any other user or group. If these conditions are not met,
sshd will refuse to start the SFTP subsystem for security reasons, resulting in the failure error.
To fix this, identify the chroot path (e.g.,
/var/www/html) and adjust ownership:
sudo chown root:root /var/www/html
sudo chmod 755 /var/www/html
Inside the chrooted directory, create a subdirectory where the user can write files, and set the ownership of that subdirectory to the specific user. This ensures the chroot environment remains secure while allowing functional file transfers.
Inspecting SELinux and AppArmor Policies
On systems with mandatory access controls enabled, such as those running SELinux on RHEL/CentOS or AppArmor on Ubuntu, the SSH daemon might be blocked from accessing the SFTP binary or the designated directories. SELinux contexts can prevent
sshd from executing certain binaries if they are not labeled correctly. You can check the audit log for denials using
sudo ausearch -m avc -ts recent. If you find denials related to
sshd and
sftp, you may need to restore default contexts with
sudo restorecon -Rv /path/to/chroot or create custom policies. Similarly, AppArmor logs can be checked in
/var/log/syslog for profile violations blocking the SFTP process.
Testing Connectivity and Debugging
Before assuming a configuration error, test the connection with verbose output to pinpoint exactly where it fails. Run the following command locally:
sftp -vvv user@host
Look for the line where it attempts to request the subsystem. If the server rejects it immediately, the issue is likely configuration-related. If the connection drops after authentication but before the prompt appears, it is almost certainly a subsystem or chroot permission issue. Additionally, ensure that the user account has a valid shell or is configured for SFTP-only access via
ForceCommand internal-sftp in the
Match block of
sshd_config. Misconfiguring the shell can sometimes interfere with subsystem initialization depending on the SSH version. For more details on setting up secure directories, see
Setting up SFTP Directory for Multiple File Sources on Linux Server.
Frequently Asked Questions
Why does the error happen only for some users?
This typically occurs when individual user configurations in
sshd_config override global settings incorrectly. Check if there is a
Match User username block that specifies a different Subsystem path or an invalid ChrootDirectory. Removing conflicting directives or correcting the paths within the Match block usually resolves the per-user issue.
Can I use an external sftp-server binary instead of internal-sftp?
Yes, but it requires careful setup. External binaries like
/usr/libexec/openssh/sftp-server allow for more complex logging and customization but do not support ChrootDirectory restrictions as securely as internal-sftp. Ensure the binary path is absolute and the file has execute permissions for the SSH daemon user.
What if the SSH service itself won't start after changing config?
If
systemctl status sshd shows a failure, the syntax in
sshd_config is likely invalid. Use
sudo sshd -t to test the configuration file for errors before restarting the service. Fix any reported syntax issues, such as typos in the Subsystem directive or missing quotes around paths.
Does firewall blocking cause this specific error?
No, firewall issues typically result in connection timeouts or "Connection refused" messages before the subsystem request is even made. The "subsystem request failed" error confirms that the TCP connection and SSH handshake succeeded, so the problem lies entirely within the SSH daemon's logic or file system permissions.
How do I reset SFTP permissions to default?
Revert any manual changes to
/etc/ssh/sshd_config by restoring it from a backup or reinstalling the package. Then, ensure the default Subsystem line reads
Subsystem sftp internal-sftp. Finally, verify that the home directories and any chroot paths adhere to the root-owned, non-writable-by-others rule.