{"id":14742,"library":"node-red-contrib-ftp","title":"Node-RED FTP/SFTP Client","description":"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.","status":"active","version":"0.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/joeartsea/node-red-contrib-ftp","tags":["javascript","node-red","ftp"],"install":[{"cmd":"npm install node-red-contrib-ftp","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-contrib-ftp","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-contrib-ftp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package provides Node-RED nodes and requires a Node-RED runtime environment to function.","package":"node-red","optional":false}],"imports":[{"note":"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.","wrong":"import { ftpIn } from 'node-red-contrib-ftp'","symbol":"ftp in node","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."},{"note":"The 'sftp in' node provides secure file transfer capabilities over SFTP within your Node-RED flows, accessed directly from the palette after installation.","wrong":"const sftp = require('node-red-contrib-ftp').sftp","symbol":"sftp in node","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."},{"note":"Configuration nodes centralize connection details, promoting reusability, security, and easier maintenance across your flows. SFTP has a similar dedicated config node.","wrong":"Hardcoding FTP server credentials directly within individual 'ftp in' node instances or `msg` objects.","symbol":"ftp config node","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."}],"quickstart":{"code":"[{\"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\":\"\"}]","lang":"json","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions <1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: connect ECONNREFUSED <host>:<port>"},{"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.","cause":"The username or password provided in the FTP/SFTP configuration node is incorrect, or the specified user lacks permission to access the server.","error":"530 Login incorrect."},{"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.","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).","error":"Error: No such file or directory"}],"ecosystem":"npm"}