ssh2-sftp-client is a promise-based SFTP client for Node.js, acting as a decorator around the robust `ssh2` package. It provides a convenient, promise-driven API for common SFTP operations such as connecting, listing directories, uploading, downloading, and managing files, abstracting away the event-based complexities of the underlying `ssh2` library. The current stable release is v12.1.1, indicating active maintenance with a regular cadence of minor and patch updates, alongside major versions for significant API changes. It officially supports Node.js versions 20.x and newer, specifically tested against Node 24.14.0, and includes specific fixes for platform quirks like those found in Microsoft SFTP servers. Its focus on promises, active bug fixing, and direct integration with the `ssh2` library makes it a reliable solution for SFTP interactions in modern Node.js environments.
npm install ssh2-sftp-clientVerified import paths — ran on the pinned version, not inferred.
Demonstrates connecting to an SFTP server, creating a directory, uploading, listing, downloading, and deleting a file, including error handling and resource cleanup.
Implement custom retry logic using a loop or a dedicated retry utility, or ensure robust error handling for initial connection attempts without expecting automatic retries from the library.
Review existing event handlers. If you rely on errors being thrown from global listeners, provide a custom event handler in the SftpClient constructor or adapt to the new logging/invalidation behavior for global events.
Upgrade your Node.js environment to version 20.x or higher to ensure compatibility, stability, and access to the latest features and security patches.
Always instantiate a new SftpClient object for each new connection attempt, especially after a successful disconnect or a connection error. Do not store and reuse `sftp` instances across multiple distinct operations.
Upgrade to `ssh2-sftp-client` version 10.0.0 or higher to mitigate CVE-2023-48795 and ensure secure SFTP connections.
Ensure you are on version 12.1.1 or higher to benefit from the fix. Implement robust error handling for network events and consider using connection health checks if persistent connections are critical, as `ECONNRESET` signifies an abrupt server-side closure.
Verify server host, port, and network accessibility. Check firewall rules on both client and server. Increase the 'timeout' option in the `connect` method if the server is known to be slow to respond, e.g., `sftp.connect({ ..., timeout: 10000 })`.Ensure your `ssh2-sftp-client` version is >= 12.1.1 to correctly handle these events and invalidate the internal connection state. Review server logs for reasons behind the connection termination. Implement application-level retry logic for operations that might be interrupted by such events.
Always return promises from within `.then()` blocks to ensure proper chaining and error propagation. For example, use `return sftp.list(path)` instead of just `sftp.list(path)`.
Adjust the `promiseLimit` option in methods like `uploadDir`/`downloadDir` (default is 10) to optimize for your environment. Experiment with values, but avoid excessively high limits which can degrade performance. Ensure sufficient server resources and network bandwidth.