hostdoc — offline cPanel/WHM/WHMCS support brain

← all runbooks

---
title: FTP will not connect
panel: cPanel / WHM
symptoms:
  - cannot log in over FTP
  - 530 error
  - directory listing fails after login
  - FileZilla will not connect
  - ftp login failed
  - cannot connect to the ftp server
  - 530 login incorrect
  - file manager in cpanel cannot connect
  - sftp port 22 refused
---

# FTP will not connect

## 1. Separate a login failure from a transfer failure

**Why:** they look identical to the customer and they are completely
different problems. A rejected login is credentials, a locked account or
a suspension. A successful login followed by an empty listing or a
hanging transfer is a firewall and passive port problem. Splitting these
two first is the whole trick of the call.

**In the terminal:** `grep -i ftp /var/log/messages` or
`/var/log/secure` shows whether the session authenticated.

**Care:** this only reads.

## 2. Check the credentials and the account

**Why:** the username is the account name, not the domain, and people
regularly try their email address. Checking that the account is not
suspended takes seconds and stops you chasing a password that was never
the problem.

**In cPanel:** Email > Email Accounts shows the account and the Connect
Devices button.

**In WHM:** Account Information > List Accounts shows the status.

**In the terminal:** `grep "^ftp:" /etc/passwd` shows the FTP account and
whether the shell is jailed.

**Care:** this only reads.

## 3. Check passive mode

**Why:** FTP in passive mode pulls the data connection from the server to
a port in a configured range. If that range is blocked, the login
succeeds and the directory listing hangs or comes back empty. It is the
most common cause of "it connects but I cannot see my files", and it
looks like a broken login to the customer.

**In the terminal:** the passive port range is in the server's
configuration. Check it against what the firewall allows.

**Care:** this only reads. Changing the range needs a firewall change
too, and the FTP service needs restarting, so it is not a change to make
on a live call without checking.

- https://docs.cpanel.net/knowledge-base/ftp/how-to-enable-ftp-passive-mode/

## 4. Check the firewall

**Why:** a security plugin that was installed or configured recently is
the usual reason a working FTP setup stopped working. It sits between
the customer and a service that was fine a week ago.

**In the terminal:** `iptables -L -n` and `firewall-cmd --list-all` show
what is allowed.

**Care:** this only reads. Do not open a port range to "get it working"
without understanding why it was closed.

- https://docs.cpanel.net/knowledge-base/general-systems-administration/how-to-configure-your-firewall-for-cpanel-services/

## 5. Offer SFTP as the answer

**Why:** SFTP on port 22 avoids passive mode entirely and works through
the same firewall rules as SSH. For a customer who is not attached to a
specific FTP client, this is the better answer and it saves you the
passive port conversation.

**In cPanel:** Email > Email Accounts > Connect Devices shows the SFTP
settings for the account.

**In the terminal:** `sftp <user>@<host>` and check that the shell is
not a jailed FTP shell.

**Care:** the customer's FTP password is normally the same as the cPanel
password unless they set a different one. Do not assume.

- https://docs.cpanel.net/knowledge-base/ftp/how-to-configure-your-sftp-client/