Skip to content

Troubleshooting

The logs

Set MAXIMUM_LOG_FILES to a value above 0 and look at LOG_FOLDER (uftpLog_YYYY-MM-DD). Each line says which client and which command, and why a connection was closed. For a problem you can reproduce, set DAEMON_MODE = false and start the server from a terminal.

I cannot connect

  • Is the server running? sudo ss -ltnp | grep uFTP should show the port.
  • Is the port open in the firewall and forwarded by the router? See Behind a NAT or a firewall.
  • 421: the server is full (MAXIMUM_ALLOWED_FTP_CONNECTION), or your address reached MAX_CONNECTION_NUMBER_PER_IP or MAX_CONNECTION_RATE_PER_IP. FileZilla with 10 simultaneous transfers uses 11 sessions.
  • 530 at the login: wrong user or password. After MAX_CONNECTION_TRY_PER_IP failed logins the address is blocked for 5 minutes (and by fail2ban for longer, if you use it: Block attacks with fail2ban).
  • The connection closes by itself: LOGIN_TIMEOUT (default 60 s to log in) or IDLE_MAX_TIMEOUT.

The login works but the listing or a transfer hangs

The data connection cannot be established. Check the passive ports (RANDOM_PORT_START to RANDOM_PORT_END): they must be open in the firewall and forwarded by the router. Behind a NAT with TLS set SERVER_IP. The log shows 425.

TLS and certificates

  • The client does not offer TLS: if FORCE_TLS = true, clients without TLS are refused. Enable explicit FTP over TLS in the client.
  • "Certificate not trusted": normal for a self-signed certificate. Trust it in the client, or use a certificate from an authority (see TLS and certificates).
  • unable to verify the first certificate: the file in CERTIFICATE_PATH has to contain your certificate first and then the intermediate ones.
  • The server does not start with TLS: the log says invalid certificate or invalid private key. The key must have no passphrase and must match the certificate.
  • A build without OpenSSL answers 502 to AUTH TLS. Rebuild with OpenSSL.

Errors with many parallel transfers

Clients such as FileZilla upload a tree of directories with many connections. Until one of them has created a directory, the others get 550 (change of directory) and 450 Parent directory does not exist, try again later. They are normal: the client retries and the files arrive. If it is too noisy, reduce the number of simultaneous transfers in the client (2 is the default of FileZilla).

A file is not complete after an upload

The log has a line STOR ... failed after N bytes with the reason. 452 means the disk is under MIN_FREE_SPACE_MB.

The server stopped

With RESPAWN_PROCESS = true a supervisor restarts it; the log says why it stopped and shows the stack trace of a crash. Please report it if it is a crash that you can reproduce.

Report a problem

Open an issue on GitHub with the version, how it was built, the relevant lines of the log and the configuration without passwords. For a security problem do not open a public issue: see Security.