Why do I see "Failed to retrieve directory listing" errors during FTP authentication attempts?

Question

Why do I see the following error during FTP authentication attempts?

CONFIG_TEXT: Failed to retrieve directory listing

Answer

FTP uses a data port and a command port to transfer information between a client and a server. During an active mode session, the command port uses port 21, and the data port uses port 20. During a passive mode session, however, the data port does not always use port 20. Instead, a data port range of 49152 through 65534 is utilized by default with passive mode sessions.

Here's an example of the output you will see in your FTP client if one or more of the ports in the passive mode range are blocked by your server's firewall, your hosting provider's firewall, or by a network router's NAT configuration settings:

CONFIG_TEXT: Status: Resolving address of mycpanelserver.tld
Status: Connecting to 0.1.2.3:21...
Status: Connection established, waiting for welcome message...
Status: Initializing TLS...
Status: Verifying certificate...
Status: TLS connection established.
Status: Connected
Status: Retrieving directory listing of "/home/cpaccount"...
Command: CWD /
Response: 250 OK. Current directory is /public_html
Command: PWD
Response: 257 "/" is your current location
Command: TYPE I
Response: 200 TYPE is now 8-bit binary
Command: PASV
Response: 227 Entering Passive Mode (10,20,10,100,256,266)
Command: MLSD
Error: Connection timed out after 60 seconds of inactivity
Error: Failed to retrieve directory listing
Status: Disconnected from server

From the output above, the FTP server fails to respond to the MLSD command after entering passive mode. Instead, the FTP connection attempt hangs, and the connection is terminated after 60 seconds of inactivity.

Server Administrators: If you have root access to the server, follow the steps documented on our How To Enable FTP Passive Mode knowledge base article provided below to first verify that passive mode is properly configured in your FTP server configuration settings. Then, scroll down to the article's Configure Your Firewall section to learn how to open these ports in your server's firewall.

How To Enable FTP Passive Mode

cPanel users or WHM resellers: If your access is limited to an individual cPanel account, report the FTP connection error to your web hosting provider along with a link to this article to explain the issue.

Note: If you need help finding your hosting provider, the following support article should help:

How To Identify Your Hosting Provider

Upstream Providers: If you have access to the upstream provider's network or firewall, check to verify that the passive mode port range is allowed over the TCP protocol. Reference your provider's network and/or firewall documentation for information on how to make firewall changes when using a cloud service provider such as AWS, Google Cloud, or DigitalOcean.