|
| 1 | +--- |
| 2 | +title: Troubleshoot Common SFTP Issues |
| 3 | +description: Explains how to resolve common SFTP issues when you use OpenSSH for Windows. |
| 4 | +ms.date: 11/05/2025 |
| 5 | +manager: dcscontentpm |
| 6 | +audience: itpro |
| 7 | +ms.topic: troubleshooting |
| 8 | +ms.reviewer: kaushika, warrenw, v-appelgatet |
| 9 | +ms.custom: |
| 10 | +- sap:system management components\openssh (including sftp) |
| 11 | +- pcy:WinComm User Experience |
| 12 | +appliesto: |
| 13 | + - ✅ <a href=https://learn.microsoft.com/windows/release-health/windows-server-release-info target=_blank>Supported versions of Windows Server</a> |
| 14 | + - ✅ <a href=https://learn.microsoft.com/windows/release-health/supported-versions-windows-client target=_blank>Supported versions of Windows Client</a> |
| 15 | +--- |
| 16 | +# Troubleshoot common SFTP issues when using OpenSSH |
| 17 | + |
| 18 | +OpenSSH on Windows provides secure file transfer protocol (SFTP) capabilities. This article describes how to resolve the most common issues that you might encounter when you use SFTP and OpenSSH to administer Windows Server and Windows Client. |
| 19 | + |
| 20 | +## Best practices and additional resources |
| 21 | + |
| 22 | +- Use the latest supported OpenSSH version. |
| 23 | +- Avoid configuring OpenSSH to use a network share for the chroot directory. |
| 24 | +- Every time that you change the OpenSSH Server configuration, validate the change by running `sshd -t`. |
| 25 | +- When you start troubleshooting, check Event Viewer for relevant events. |
| 26 | + |
| 27 | +For more information about how to configure OpenSSH on Windows and Windows Server, see the following articles: |
| 28 | + |
| 29 | +- [Get started with OpenSSH for Windows](/windows-server/administration/openssh/openssh_install_firstuse) |
| 30 | +- [OpenSSH Server configuration for Windows Server and Windows](/windows-server/administration/openssh/openssh-server-configuration) |
| 31 | + |
| 32 | +### How to enable SFTP logging |
| 33 | + |
| 34 | +To enable SFTP logging for the OpenSSH Server service, modify the sshd_config file, and then restart the OpenSSH Server service. Follow these steps: |
| 35 | + |
| 36 | +1. Use an administrator-level account to open a text editor, and then open **%ProgramData%\ssh\sshd_config**. The default text of the "Logging" section should resemble the following excerpt: |
| 37 | + |
| 38 | + ```output |
| 39 | + # Logging |
| 40 | + #SyslogFacility AUTH |
| 41 | + #LogLevel INFO |
| 42 | + ``` |
| 43 | + |
| 44 | +1. To enable SFTP logging, edit the text to resemble the following excerpt: |
| 45 | + |
| 46 | + ```output |
| 47 | + # Logging |
| 48 | + SyslogFacility LOCAL0 |
| 49 | + LogLevel DEBUG3 |
| 50 | + ``` |
| 51 | + |
| 52 | + Also, add (or modify) the following text: |
| 53 | + |
| 54 | + ```output |
| 55 | + Subsystem sftp sftp-server.exe -f LOCAL0 -l DEBUG3 |
| 56 | + ``` |
| 57 | + |
| 58 | +1. Save and close the sshd_config file. |
| 59 | + |
| 60 | +1. To restart the OpenSSH Server service, open a Windows Command Prompt window, and then run the following command: |
| 61 | + |
| 62 | + ```console |
| 63 | + NET STOP "OpenSSH SSH Server" && NET START "OpenSSH SSH Server" |
| 64 | + ``` |
| 65 | + |
| 66 | +After the service restarts, it generates SFTP log data in %ProgramData%\ssh\logs. For more information about OpenSSH logging, see [How to enable OpenSSH verbose logging](enable-openssh-verbose-logging.md). |
| 67 | + |
| 68 | +## Common SFTP issues on Windows and Windows Server |
| 69 | + |
| 70 | +### SFTP users land in the wrong directory or outside the chroot jail |
| 71 | + |
| 72 | +When correctly configured, the chroot directory restricts (jails) users to a specific directory tree. This restriction prevents users from accessing the rest of the file system. |
| 73 | + |
| 74 | +Check the following settings: |
| 75 | + |
| 76 | +- In the sshd_config file, make sure that `ChrootDirectory` points to a local directory and doesn't use a UNC path. |
| 77 | +- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory. |
| 78 | +- Make sure that each user has a writeable directory within the chroot directory, and that the directory has the correct permissions. Secure the /.ssh/authorized_keys files. |
| 79 | + |
| 80 | + > [!NOTE] |
| 81 | + > To verify and fix NTFS permissions, use the [icacls](/windows-server/administration/windows-commands/icacls) command in an administrative Command Prompt window. |
| 82 | +
|
| 83 | +- In the sshd_config file, use`ForceCommand internal-sftp`, and use the `-d` switch together with the `Subsystem sftp sftp-server.exe` command to set an upload directory. You can use these settings in `Match` blocks to specify users. |
| 84 | + |
| 85 | +### Specific users can't use SFTP or they receive "Access denied" errors |
| 86 | + |
| 87 | +This behavior indicates ownership or permissions issues. Check the following settings: |
| 88 | + |
| 89 | +- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory. |
| 90 | +- Make sure that each user has a writeable directory within the chroot directory, and that the directory has the correct permissions. Secure the /.ssh/authorized_keys files. |
| 91 | + |
| 92 | + > [!NOTE] |
| 93 | + > To verify and fix NTFS permissions, use the [icacls](/windows-server/administration/windows-commands/icacls) command in an administrative Command Prompt window. |
| 94 | +
|
| 95 | +### Users can't sign in or they receive "Authentication failed" or "Server refused our key" |
| 96 | + |
| 97 | +This behavior indicates public key or password issues. Check the following configurations: |
| 98 | + |
| 99 | +- Use C:\ProgramData\ssh\administrators_authorized_keys to store keys, and use `icacles` to check the file and folder permissions. |
| 100 | +- If the server refuses the key, add the following lines to sshd_config: |
| 101 | + |
| 102 | + ```console |
| 103 | + PubkeyAcceptedKeyTypes +ssh-rsa |
| 104 | + HostKeyAlgorithms +ssh-rsa |
| 105 | + ``` |
| 106 | + |
| 107 | + > [!NOTE] |
| 108 | + > After you make these changes, restart the OpenSSH Server service. |
| 109 | +
|
| 110 | +### OpenSSH Server service doesn't start, or SFTP connections hang |
| 111 | + |
| 112 | +To resolve these issues, try the following actions: |
| 113 | + |
| 114 | +- To validate the sshd_config settings, run the `sshd -t` command. |
| 115 | +- Review Event Viewer for any relevant events. |
| 116 | +- To check and repair Access Control Lists (ACLs) on the chroot directory tree, run the `icacles` command. |
| 117 | +- Review the sshd_config settings. Make sure that the entries don't have any trailing spaces, and make sure that the `Subsystem sftp sftp-server.exe` command is present. |
| 118 | + |
| 119 | +If none of these actions resolve the issue, uninstall and reinstall OpenSSH Server. |
| 120 | + |
| 121 | +### SFTP logs are missing or incomplete |
| 122 | + |
| 123 | +Review the log settings in ssdh_config. SFTP log data is stored in %ProgramData%\ssh\logs. |
| 124 | + |
| 125 | +To check and repair ACLs on the log folder, run the `icacles` command. |
| 126 | + |
| 127 | +### Users can't upload or download files |
| 128 | + |
| 129 | +- In the sshd_config file, make sure that `ChrootDirectory` points to a local directory and doesn't use a UNC path. |
| 130 | +- Make sure that SYSTEM/Administrators has owner permissions on the chroot directory. |
| 131 | +- Make sure that each user has a writeable directory within the chroot directory, and that the directory has the correct permissions. To check and repair ACLs, run the `icacles` command. |
| 132 | +- Make sure that users don't have writer permission on the chroot directory. |
0 commit comments