Node.js FTP Client

Common errors

• TypeError: require(...) is not a constructor

  cause Attempting to use `new Client()` after importing `ftp` with an `import` statement in an ESM context, or incorrectly destructuring the CommonJS export.
  fix Ensure your file is treated as CommonJS and use `const Client = require('ftp');` to import the module. The `Client` is directly the exported constructor.

• Error: connect ETIMEDOUT

  cause The client failed to establish a connection to the FTP server within the specified `connTimeout` period, often due to an incorrect host/port, server not running, or network/firewall issues.
  fix Verify the `host` and `port` in your `connect()` configuration. Check if the FTP server is running and accessible from the client's network. Increase `connTimeout` if network latency is expected.

• Error: EPROTO: protocol error, errno -1

  cause A generic FTP protocol error, often indicating a problem during the FTP command/response sequence, potentially related to server misconfiguration, unsupported features, or deprecated TLS settings. Error objects usually contain a `code` property for the FTP response code.
  fix Inspect the `err.code` property for the specific FTP response code. Check server logs for more details. If using TLS, ensure compatible `secure` options and `secureOptions` are set, as older libraries might struggle with modern TLS versions/configs.

• DEP0064] DeprecationWarning: tls.createSecurePair() is deprecated. Please use tls.TLSSocket instead.

  cause This warning indicates that the underlying Node.js `tls` module methods used by `node-ftp` for establishing secure connections are deprecated in newer Node.js versions. This is due to the package's age.
  fix While this warning might not immediately break functionality, it highlights the package's outdated dependencies. There is no direct fix within `node-ftp` itself. Consider migrating to a modern, actively maintained FTP client like `basic-ftp` which uses up-to-date Node.js APIs.

Warnings

• breaking The `secure` option's `'implicit'` value for implicitly encrypted control connections is deprecated in modern FTP/FTPS contexts and may not work reliably with contemporary servers or Node.js TLS versions.
  Fix: Prefer `secure: true` for explicit FTPS (AUTH TLS) or `secure: 'control'` if only the control connection needs encryption. For new projects, consider modern FTP client libraries like `basic-ftp` that offer better TLS support.
• gotcha This package is unmaintained, with the last release in 2016 and last commit in 2018. It does not receive security updates or bug fixes, making it potentially vulnerable to discovered FTP protocol exploits or Node.js compatibility issues.
  Fix: For new projects, use actively maintained Node.js FTP/FTPS client libraries such as `basic-ftp` which supports modern features like Promises, async/await, FTPS, and TypeScript.
• gotcha The library exclusively uses CommonJS `require()` syntax and does not support ES Modules (`import`). Attempting to use `import` will lead to runtime errors in modern Node.js environments configured for ESM.
  Fix: Ensure your project or file uses CommonJS (`.js` files without `"type": "module"` in `package.json`, or `.cjs` files) and imports the library using `const Client = require('ftp');`.
• gotcha The `connTimeout` and `pasvTimeout` configurations default to 10 seconds. In environments with high latency or strict firewalls, these timeouts might be insufficient, leading to connection or data transfer failures.
  Fix: Increase `connTimeout` and `pasvTimeout` values in the `connect()` configuration object to accommodate network conditions, e.g., `{ connTimeout: 30000, pasvTimeout: 30000 }`.

Install

• npm install ftp npm
• yarn add ftp yarn
• pnpm add ftp pnpm

Imports

• Client
  wrong:

  import { Client } from 'ftp'

  correct:

  const Client = require('ftp')

  The package is CommonJS-only (published in 2016) and does not support ES Modules `import` syntax. Attempting to use `import` will result in a runtime error.
• Client (type/constructor)
  wrong:

  import Client from 'ftp';

  correct:

  const Client = require('ftp');
  const c = new Client();

  The `Client` symbol is a constructor function exported directly from the main module. There is no default export, and it must be instantiated with `new Client()`.
• Events

  c.on('ready', () => { /* ... */ });
  c.on('error', (err) => { /* ... */ });

  The client uses an event-driven pattern, emitting events like `ready`, `error`, `greeting`, `close`, and `end`. Correctly handling the `error` event is crucial.

Quickstart

This example demonstrates connecting to an FTP server, downloading a specified remote file, and saving it to the local filesystem using streams. It includes error handling and utilizes environment variables for connection configuration.

const Client = require('ftp');
const fs = require('fs');

const FTP_HOST = process.env.FTP_HOST ?? 'localhost';
const FTP_PORT = parseInt(process.env.FTP_PORT ?? '21', 10);
const FTP_USER = process.env.FTP_USER ?? 'anonymous';
const FTP_PASSWORD = process.env.FTP_PASSWORD ?? 'anonymous@';
const REMOTE_FILE = process.env.REMOTE_FILE ?? 'remote-file.txt';
const LOCAL_COPY_FILE = process.env.LOCAL_COPY_FILE ?? 'local-copy.txt';

const c = new Client();
c.on('ready', function() {
  console.log(`Connected to ${FTP_HOST}:${FTP_PORT}. Attempting to download ${REMOTE_FILE}...`);
  c.get(REMOTE_FILE, function(err, stream) {
    if (err) {
      console.error('Error downloading file:', err.message, err.code ? `(Code: ${err.code})` : '');
      c.end();
      return;
    }
    stream.once('close', function() {
      console.log(`Successfully downloaded ${REMOTE_FILE} to ${LOCAL_COPY_FILE}.`);
      c.end();
    });
    stream.pipe(fs.createWriteStream(LOCAL_COPY_FILE));
  });
});

c.on('error', function(err) {
  console.error('FTP Client Error:', err.message, err.code ? `(Code: ${err.code})` : '');
});

c.on('end', function() {
  console.log('FTP connection ended.');
});

c.on('close', function(hadErr) {
  console.log('FTP connection closed. Had error:', hadErr);
});

c.connect({
  host: FTP_HOST,
  port: FTP_PORT,
  user: FTP_USER,
  password: FTP_PASSWORD,
  secure: false // Set to 'true' or 'control' for FTPS, 'implicit' for implicit FTPS (deprecated)
});