Node-RED FTP/SFTP Client

0.0.8 · active · verified Sun Apr 19

node-red-contrib-ftp is a Node-RED package providing nodes for interacting with FTP and SFTP servers. It enables Node-RED flows to perform various file operations such as listing, getting, putting, appending, deleting, and creating directories on remote servers. The package includes an 'ftp in' node for standard FTP operations and an 'sftp in' node for secure file transfer via SFTP. As of version 0.0.8, it integrates directly into the Node-RED editor palette, offering a visual way to manage file transfers. Node-RED contrib packages typically follow the Node-RED release cycle, but individual package updates vary. Key differentiators include its tight integration with Node-RED's flow-based programming model, allowing for easy automation of file transfer tasks within larger workflows without writing custom code.

Common errors

```
Error: connect ECONNREFUSED <host>:<port>
```
cause The Node-RED instance could not establish a connection to the specified FTP/SFTP server. This often means the server address or port in the configuration node is incorrect, the server is down, or a firewall is blocking the connection from the Node-RED host.

fix Verify the host and port in your FTP/SFTP configuration node. Check if the server is running and accessible from the machine hosting Node-RED. Review local and network firewall rules.
```
530 Login incorrect.
```
cause The username or password provided in the FTP/SFTP configuration node is incorrect, or the specified user lacks permission to access the server.

fix Double-check the username and password in your FTP/SFTP configuration node. Ensure the credentials are valid for the target server and that the user has appropriate access rights for the attempted operations.
```
Error: No such file or directory
```
cause The specified remote `msg.filename` or local `msg.localFilename` (if used) does not exist for the attempted operation (e.g., GET, DELETE, APPEND to a non-existent file).

fix Verify the exact path and filename for both remote and local files. For local files, ensure the Node-RED process has appropriate read/write permissions to the specified directory.

Warnings

gotcha This package provides Node-RED 'contrib' nodes. It must be installed into a Node-RED runtime environment and is configured visually in the flow editor, not used as a programmatic JavaScript library. Attempting to `require()` or `import` symbols will fail.
Fix: Ensure Node-RED is installed and running. Install this package via `npm install node-red-contrib-ftp` in your Node-RED user directory, or use the Node-RED Palette Manager. The nodes will then appear in your editor's palette.
gotcha FTP and SFTP server connection details (host, port, credentials) are managed within shared configuration nodes. Incorrect, incomplete, or missing configuration will lead to connection failures and errors in your flow.
Fix: Properly configure the 'ftp' or 'sftp' configuration node (accessed when editing the respective operation node) with valid server details and credentials. Utilize Node-RED's credential storage or environment variables for sensitive information like passwords.
gotcha Operations like GET, PUT, and APPEND require both `msg.filename` (the path/name of the file on the remote server) and `msg.localFilename` (the path/name of the file on the local machine running Node-RED, or a Buffer). Mismatched or missing properties will cause errors.
Fix: Ensure the incoming `msg` object has the correct `filename` and `localFilename` properties set according to the desired FTP/SFTP operation. For PUT/APPEND, `msg.payload` can also serve as the local file content if `msg.localFilename` is omitted.
gotcha The package version 0.0.8 indicates a relatively early stage of development. Users should be aware that future versions, especially before a 1.0.0 release, might introduce breaking changes more frequently than mature libraries.
Fix: Monitor the project's GitHub repository for updates and review release notes carefully before upgrading, especially for mission-critical applications to avoid unexpected behavior.

Install

npm install node-red-contrib-ftp npm
yarn add node-red-contrib-ftp yarn
pnpm add node-red-contrib-ftp pnpm

Imports

ftp in node
wrong:
```
import { ftpIn } from 'node-red-contrib-ftp'
```
correct:
```
Install via `npm install node-red-contrib-ftp` in your Node-RED user directory, then drag the 'ftp in' node from the Node-RED palette into your flow.
```
Node-RED nodes are used visually within the flow editor, not programmatically imported into JavaScript/TypeScript code. The 'ftp in' node handles FTP client operations like GET, PUT, LIST.

sftp in node

wrong:

const sftp = require('node-red-contrib-ftp').sftp

correct:

Install via `npm install node-red-contrib-ftp` in your Node-RED user directory, then drag the 'sftp in' node from the Node-RED palette into your flow.

The 'sftp in' node provides secure file transfer capabilities over SFTP within your Node-RED flows, accessed directly from the palette after installation.

ftp config node

wrong:

Hardcoding FTP server credentials directly within individual 'ftp in' node instances or `msg` objects.

correct:

Configure a shared 'ftp' configuration node (accessible via 'Add new ftp config...' when editing an 'ftp in' node) to define connection parameters (host, port, user, password) for multiple FTP operations.

Configuration nodes centralize connection details, promoting reusability, security, and easier maintenance across your flows. SFTP has a similar dedicated config node.

Quickstart

This Node-RED flow demonstrates how to use the 'ftp in' node to first list files on a remote FTP server, then delete a specific file named 'test.csv', and finally list the files again to confirm the deletion. It uses inject nodes to trigger the operations and a debug node to display the results. Replace placeholder FTP host and credentials in the 'ftp' config node with your own details, ideally using environment variables.

[{"id":"91039113.5ae0b8","type":"debug","z":"e052b363.bcca48","name":"Output Debug","active":true,"console":"false","complete":"payload","x":494,"y":72,"wires":[]},{"id":"ebf6cb8.83c77b8","type":"inject","z":"e052b363.bcca48","name":"Trigger Delete","topic":"","payload":"","payloadType":"none","repeat":"","crontab":"","once":false,"x":114,"y":141,"wires":[["18704d55.fa8d63"]]},{"id":"18704d55.fa8d63","type":"function","z":"e052b363.bcca48","name":"Set Filename for Delete","func":"msg.filename = 'test.csv';\nreturn msg;","outputs":1,"noerr":0,"x":270,"y":141,"wires":[["6f4f3dda.a20a7c"]]},{"id":"6f4f3dda.a20a7c","type":"ftp in","z":"e052b363.bcca48","ftp":"a7676b1a.e9714","operation":"delete","filename":"","localFilename":"","name":"Delete Remote File","x":440,"y":143,"wires":[["be82074.47a8878"]]},{"id":"8e30f382.5971f8","type":"inject","z":"e052b363.bcca48","name":"Trigger List","topic":"","payload":"","payloadType":"none","repeat":"","crontab":"","once":false,"x":108,"y":67,"wires":[["be82074.47a8878"]]},{"id":"be82074.47a8878","type":"ftp in","z":"e052b363.bcca48","ftp":"a7676b1a.e9714","operation":"list","filename":"","localFilename":"","name":"List Remote Files","x":276,"y":68,"wires":[["91039113.5ae0b8"]]},{"id":"a7676b1a.e9714","type":"ftp","z":"","host":"${process.env.FTP_HOST ?? 'YOUR_FTP_HOST'}","port":"21","secureOptions":"","user":"${process.env.FTP_USERNAME ?? 'YOUR_USERNAME'}","connTimeout":"","pasvTimeout":"","keepalive":""}]

view raw JSON →