File transfers can fail for a number of reasons. Maybe the server ran out of space. Maybe you mistyped a path. Maybe your firewall blocked the data connection. Whatever went wrong, the server will generate an error code, which may seem cryptic at first glance but actually shows you exactly what the problem is.
Understanding these codes transforms debugging from random guessing into targeted fixes. Here's what each code means, which ones actually matter, and how to troubleshoot the common failures.
How SFTP and FTP error codes work
FTP, FTPS, and SFTP all communicate through status and error codes, but they structure them differently. These error codes are also known as server return codes and are used to explain if a connection is made and if there is an error, what the specific issue is.
FTP uses three-digit error codes, with the first digit being the general category, such as success or failure. The second digit groups into a more specific category, such as syntax or authentication, while the third is the precise issue within that category.
SFTP uses simple single or double-digit codes and combines them with a text description. For example, code 4 is simply Failure, which indicates that an unspecified error has occurred.
The three-tier structure of FTP server return codes makes them more specific than SFTP, which helps when you're troubleshooting.
However, when SFTP codes come with specific text explanations, they can be a handy way to quickly debug an issue. The problem is that not all servers support all codes. For instance, many simply use code 4 for any issue, even ones that have a dedicated error code elsewhere, which can make debugging much more difficult.
FTP and FTPs error code structure
As mentioned above, FTP and FTPS use three-digit codes. Each digit in the code represents a specific type of issue that you can quickly drill down to the problem once you understand what the codes represent.
First digit - General category - This category shows whether a connection is successful, failed, or is incomplete.
- 1xx - Positive Preliminary (action started, waiting for more)
- 2xx - Positive Completion (success)
- 3xx - Positive Intermediate (need more information)
- 4xx - Transient Negative (temporary failure, retry might work)
- 5xx - Permanent Negative (permanent failure, won't work if you retry)
- 6xx - Protected Reply (the actual message is one of the 1xx-5xx codes but is encoded)
Second digit - Specific category - This is the subcategory that the status falls into.
- x0x - Syntax
- x1x - Information
- x2x - Connection
- x3x - Authentication
- x4x - Unspecified
- x5x - File system
The third digit is the detailed information about the issue. Because this is specific to a subcategory, there is no general structure used for the last digit.
Common FTP/FTPS Codes
Below, we've compiled a list of common server return codes for FTP and FTPS connections and broken them down by general category so you can quickly check what a specific code means and what to do, if anything, for troubleshooting.
Success Codes (1xx-2xx)
These codes are returned on success, so you will rarely come across them unless you are specifically searching through log files.
| Code | Name | Meaning |
|---|---|---|
| 150 | File Status OK | Server is opening data connection for transfer |
| 200 | Command Okay | Command received and understood |
| 226 | Closing Data Connection | Transfer complete, data connection closing |
| 230 | User Logged In | Authentication succeeded |
Authentication Codes (3xx)
These codes relate to authentication, such as logging in to establish a connection to the server.
| Code | Name | Meaning | What to Do |
|---|---|---|---|
| 331 | User Name Okay | Username accepted, awaiting password | Provide password to continue |
| 332 | Need Account | Account credentials required | Ask a server administrator to create an account or send you credentials |
| 336 | User name okay, Challenge is"...." | Server is requesting a valid challenge response to craft a valid password | Respond appropriately to the challenge. Contact a server admin if you don't have this information |
Temporary Failures (4xx)
These codes mean something went wrong, but it is a temporary issue so trying again might work. The issue could be temporary server load, network hiccups, or resource constraints that might clear up.
| Code | Name | Common Causes | What to Do |
|---|---|---|---|
| 421 | Service Not Available | Server maintenance, connection limit reached, authorization failure | Wait and retry. Contact a server administrator if it persists |
| 425 | Cannot Open Data Connection | Failed to establish data connection | Switch between passive and active mode. Check firewall rules for data port access. |
| 426 | Transfer Aborted | Data connection closed during transfer | Log back in and retry. Check storage quotas. Test with firewall temporarily disabled |
| 450 | File Action Not Taken | File temporarily unavailable (possibly locked) | Wait briefly and retry - another process may have the file open |
| 451 | Local Error | Server error during processing | Verify command syntax and parameters |
| 452 | Insufficient Storage | Out of disk space or quota exceeded | Delete or archive files. Request additional storage from an administrator |
Permanent Failures (5xx)
When you see a 5xx code, retrying won't help. These indicate configuration problems, permission issues, or fundamental mismatches between what you're asking for and what the server supports.
| Code | Name | Common Causes | What to Do |
|---|---|---|---|
| 500 | Syntax Error | Command not recognized | Check for typos. Verify the server supports the command |
| 501 | Parameter Error | Command valid, but parameters are incorrect | Review input for extra spaces, special characters, or formatting issues |
| 502 | Not Implemented | Server doesn't support this command | Check server capabilities and use alternative command |
| 503 | Bad Sequence | Commands sent in wrong order | Review proper command sequence. Some operations require prerequisites like logging in first |
| 530 | Not Logged In | Authentication failed or incorrect credentials | Check username and password. Verify authentication method. |
| 532 | Need Account for storing files | User lacks permission to store files | Contact administrator for write permissions |
| 550 | File Unavailable | File doesn't exist, wrong path, or insufficient permissions | Verify correct server and file path. Check permissions. Contact administrator if access should be granted |
| 552 | Requested file action aborted. Exceeded storage allocation. | Client aborted transfer, server stopped, or quota exceeded | Check available storage and quota. Delete unnecessary files |
| 553 | Invalid Filename | Filename contains invalid characters | Rename file, removing special characters and spaces |
Unique security codes for FTSP servers
FTPS adds SSL/TLS on top of FTP, which introduces a few security-specific codes. These relate to certificate validation and encryption negotiation.
| Code | Name | Meaning | What to Do |
|---|---|---|---|
| 234 | Security Negotiation Successful | TLS handshake started | Normal FTPS connection flow |
| 431 | Unavailable Resources | SSL certificate or encryption method missing | Contact administrator to configure SSL/TLS certificates |
| 534 | Policy Requires SSL | Server requires SSL/TLS for secure communication | Configure client to use FTPS (FTP over SSL/TLS) |
FTP 6xx codes
Codes with a six as the first digit (6xx) fall into the protected reply category. These are used as a camouflage to disguise other codes that would be sent for security reasons. For example, code 331 would normally indicate that a username is correct, which an attacker could then use as a focus by guessing the password to that verified username.
Only valid users should be able to decode 6xx codes, which they can then use for troubleshooting as above.
How SFTP Codes Work
SFTP uses simpler codes (0-31), but most servers only implement version 3, which defines codes 0-8. You'll usually see descriptive text instead of raw numbers.
Most SSH/SFTP servers, including OpenSSH, only support SFTP protocol version 3. The additional codes (9-31) defined in later versions rarely appear in production.
Common SFTP Status Codes
SFTP's architecture is simpler than FTP but provides less detail when things go wrong. Where FTP gives you specific three-digit codes, SFTP often returns generic failures that require more investigative work, especially when they only return codes 0-8.
Core Codes (Version 3 - Widely supported)
| Code | Name | Meaning | What to Do |
|---|---|---|---|
| 0 | SSH_FX_OK | Success | Operation completed |
| 1 | SSH_FX_EOF | End of file | Normal when reading to the end of a file or finishing directory listing |
| 2 | SSH_FX_NO_SUCH_FILE | File doesn't exist | Verify path is correct and file exists |
| 3 | SSH_FX_PERMISSION_DENIED | Insufficient permissions | Check user, file, and directory permissions. Review SSH config if needed |
| 4 | SSH_FX_FAILURE | Generic failure error | See detailed notes below - this can cover many scenarios |
| 5 | SSH_FX_BAD_MESSAGE | Malformed request | Client software bug. Update client or report issue to developers |
| 6 | SSH_FX_NO_CONNECTION | No connection exists | Client-generated code. Check network connectivity and verify server is reachable |
| 7 | SSH_FX_CONNECTION_LOST | Connection dropped during operation | Check network stability. Verify server is running. Look for firewall or timeout issues. Re-establish connection |
| 8 | SSH_FX_OP_UNSUPPORTED | Operation not supported | Check that the operation should be supported by the server. Avoid features from newer versions. |
Understanding Code 4 (Failure)
OpenSSH, an open source tool for communicating via the SSH protocol, uses Code 4 as a catch-all. It often returns just "Failure" with no additional context, which makes troubleshooting harder than with FTP's specific codes.
Common scenarios that return code 4:
- Renaming file to existing filename
- Creating a directory that already exists
- Moving file across different filesystems
- Exceeding disk quota
How to troubleshoot code 4:
Start with disk space since it's the most common culprit. Run df -h to check the details on the disk space, which will show you the used and available server disk space in a human-readable format. If there's space available, check if you're trying to create something that already exists and list the directory contents to verify.
If that doesn't work, you can try confirming permissions with ls -la on the target location, which will display permissions such as drw (read and write permissions on the directory). When you don't have the right permissions for the action you are attempting to take, it won't be possible to complete the action.
If you're still stuck, check the server logs, which you should be able to view at /var/log/auth.log or /var/log/secure for more context that didn't make it back to the client.
Extended Codes (Version 4+)
Most production servers don't support these. OpenSSH will return code 4 (Failure) instead.
| Code | Name | Meaning |
|---|---|---|
| 9 | SSH_FX_FILE_ALREADY_EXISTS | Creating file that already exists |
| 10 | SSH_FX_WRITE_PROTECT | File or filesystem is write-protected |
| 11 | SSH_FX_NO_MEDIA | Removable media not present |
| 12 | SSH_FX_NO_SPACE_ON_FILESYSTEM | Insufficient disk space |
| 13-31 | Various | Quota exceeded, invalid handles, lock conflicts, etc. |
Quick Debugging Tips
When something fails, there are a few things you can try to debug many issues. Both protocols include human-readable error text alongside the numeric codes. Adding the -h flag will make the information easier to parse.
For FTP connections, remember that the first digit of an FTP code tells you the underlying issue. This will le you know if retrying makes sense; for 4xx codes, the issue could be resolved on its own and retrying could work, while 5xx means you need to fix the underlying issue first. You can also try the opposite connection mode if connections fail. If you're using PASV, try PORT, or vice versa.
For SFTP, code 4 means you need to dig into context clues and server logs. See the section on above on understanding code 4 for more details.
For connection issues, test port accessibility with tools like NCat or Nmap, which you can find more about at nmap.org. You can also check server logs with journalctl -u ssh.service on systemd systems, or /var/log/auth.log (Debian/Ubuntu) and /var/log/secure (RHEL/CentOS) on traditional systems.
If you're still stuck, test with a different client to rule out client-specific bugs, and check disk space with df -h since full filesystems are a common culprit. You can also try contacting a server admin directly for assistance if you believe you should be able to perform the action and troubleshooting isn't working.
Debugging FTP and SFTP errors with Couchdrop
Couchdrop is the modern SFTP platform for b2b file transfers, file-based automation, and data flows. A cloud SFTP server is provisioned automatically for you immediately at sign up with no downloads or infrastructure required. With your server, debugging is straightforward and you can check all system events and user activities in the Activity Log, which includes summarized details as well as the full raw event information.
For example, if a user tries to login from an SFTP client but mistypes the password, the message will say that login failed for the user, show their IP address and method for logging in (such as an sftp client), and that the password does not match.
To try Couchdrop for yourself, you can register for an account and get instant access for 14 days with no credit card required. Sign up now to start your trial.