File Handler node

The File Handler node performs file operations across SFTP servers and cloud storage buckets (AWS S3, GCP, MinIO). Use it to transfer files between systems, read file contents, manage files on remote servers, and extract compressed archives within your workflows.

When to use

Transfer files from SFTP servers to cloud storage buckets
Move files between different SFTP servers
Read file contents from SFTP for processing in workflows
Delete processed files from SFTP servers or cloud buckets
Extract compressed archives (zip, tar, gz, tgz) on remote servers
List files in SFTP directories for batch processing

This node is recommended for files greater than 5MB. For smaller files, use the CSV/Excel node instead.

Common parameters

Several actions share common SFTP connection parameters. These are documented once here for reference.

SFTP Connection Parameters

Host

string

required

SFTP server hostname or IP address. Example: sftp.example.com or {{config.sftp_host}}

Port

integer

required

SFTP server port. Default: 22

Username

string

required

SFTP username for authentication. Supports dynamic variables. Example: sftp_user or {{env.SFTP_USERNAME}}

Password

string

Password for SFTP authentication. Use this if not using PEM key authentication. Supports dynamic variables. Example: {{env.SFTP_PASSWORD}}

PEM Key

string

SSH private key in PEM format for key-based authentication. Use this if not using password authentication. Supports dynamic variables.

PEM Key Passphrase

string

Passphrase for the PEM private key, if the key is passphrase-protected. Supports dynamic variables.

Store SFTP credentials as environment variables under Organization > Settings > Environment Variable for secure, reusable configuration.

Source/Destination File Details

Used in transfer actions to specify file locations.

Protocol

dropdown

required

The protocol for accessing the file. The source supports SFTP or URL. The destination supports SFTP only.

When Protocol is SFTP:

Host, Port, Username, Password, File Path, PEM Key, PEM Key Passphrase (see SFTP Connection Parameters)

When Protocol is URL (source only):

URL

string

required

Public URL of the file to transfer. Example: https://example.com/files/export.csv or {{previous_node.file_url}}

Actions

Delete file from Refold bucket

Deletes a file from the Refold-managed cloud storage bucket (AWS S3, GCP, or MinIO) using the file key or file ID.

File Key

string

required

The file path/name in the bucket. Example: uploads/contacts/export-2024.csv or {{uploaded_file.key}}

File ID

string

The file identifier (ETag for S3/MinIO, generation for GCP). Use this for version-specific deletion. Example: 33a64df551425fcc55e4d42a148795d9f25f89d4

Transfer file from source to destination

Transfers a file from one SFTP server to another. The source can be an SFTP server or a URL, but the destination must be an SFTP server — so the supported transfers are SFTP-to-SFTP and URL-to-SFTP.

Source File Details

object

required

Configuration for the source file location. Select protocol (SFTP or URL) and provide corresponding connection details.

Destination File Details

object

required

Configuration for the destination file location. Select protocol (SFTP or URL) and provide corresponding connection details.

SFTP Protocol Fields:

Field	Required	Description
Protocol	Yes	Select `SFTP`
Host	Yes	SFTP server hostname
Port	Yes	SFTP port (default: 22)
Username	Yes	SFTP username
Password	No	Password (if not using PEM key)
File Path	Yes	Full path to the file
PEM Key	No	SSH private key in PEM format (if not using password)
PEM Key Passphrase	No	Passphrase for the PEM key (if passphrase-protected)

URL Protocol Fields (source only):

Field	Required	Description
Protocol	Yes	Select `URL`
URL	Yes	Public URL of the file

Transfer file from source to cobalt bucket

Transfers a file from an SFTP server to the Refold-managed cloud storage bucket and returns a presigned URL for access.

Source File Details

object

required

Configuration for the source file. The source protocol is SFTP; provide the SFTP connection details.

Bucket Object Settings

object

Configuration for the uploaded file in the bucket.

Bucket Object Settings:

Field	Type	Description
Infinite Expiry	Toggle	When enabled, the file does not expire.
TTL	Integer	Time-to-live in seconds before the file is deleted. Only applies when Infinite Expiry is disabled.
Preserve Cloud Provider Presigned URL	Toggle	When enabled, returns the cloud provider’s native presigned URL instead of Refold’s URL.

Read file from SFTP

Reads and downloads a file from an SFTP server. The file content is returned for use in subsequent workflow steps.

Host

string

required

SFTP server hostname. Example: sftp.example.com

Port

integer

required

SFTP server port. Default: 22

Username

string

required

SFTP username for authentication.

Password

string

Password for SFTP authentication (if not using PEM key).

File Path

string

required

Full path to the file on the SFTP server. Example: /uploads/exports/contacts-2024.csv

PEM Key

string

SSH private key in PEM format for key-based authentication (if not using password).

PEM Key Passphrase

string

Passphrase for the PEM key (if passphrase-protected).

Delete file from SFTP

Deletes a file from an SFTP server.

Host

string

required

SFTP server hostname. Example: sftp.example.com

Port

integer

required

SFTP server port. Default: 22

Username

string

required

SFTP username for authentication.

Password

string

Password for SFTP authentication (if not using PEM key).

File Path

string

required

Full path to the file to delete. Example: /uploads/exports/contacts-2024.csv

PEM Key

string

SSH private key in PEM format for key-based authentication (if not using password).

PEM Key Passphrase

string

Passphrase for the PEM key (if passphrase-protected).

Extract file on SFTP server

Extracts a compressed archive file directly on the SFTP server. Supports zip, tar, gz, and tgz formats.

Host

string

required

SFTP server hostname. Example: sftp.example.com

Port

integer

required

SFTP server port. Default: 22

Username

string

required

SFTP username for authentication.

Password

string

Password for SFTP authentication (if not using PEM key).

File Path

string

required

Full path to the compressed file. Example: /uploads/archive.zip

Extract To

string

Destination directory for extracted files. Example: /downloads/extracted-files/

PEM Key

string

SSH private key in PEM format for key-based authentication (if not using password).

PEM Key Passphrase

string

Passphrase for the PEM key (if passphrase-protected).

Supported archive formats: zip, tar, gz, tgz

List files in SFTP folder

Lists all files in a specified folder on an SFTP server. Use this to discover files for batch processing.

Host

string

required

SFTP server hostname. Example: sftp.example.com

Port

integer

required

SFTP server port. Default: 22

Username

string

required

SFTP username for authentication.

Password

string

Password for SFTP authentication (if not using PEM key).

Folder Path

string

required

Path to the folder to list. Example: /uploads/exports/

PEM Key

string

SSH private key in PEM format for key-based authentication (if not using password).

PEM Key Passphrase

string

Passphrase for the PEM key (if passphrase-protected).

Move file to Refold bucket (deprecated)

This action is deprecated and will be removed in a future version. Use Transfer file from source to cobalt bucket instead.

Moves a file from a URL to the Refold bucket.

Source File URL

string

required

Public URL of the file to move. Example: https://example.com/files/document-2024.pdf

TTL

integer

Time-to-live in seconds for the file in the bucket. Example: 86400 (24 hours)

File Name

string

Destination path/name in the bucket. Example: uploads/documents/document-2024.pdf

Presign URL

toggle

When enabled, returns a presigned URL for the uploaded file.

Presigned URL TTL

integer

Time-to-live in seconds for the presigned URL. Example: 3600 (1 hour)

Output

Delete file from Refold bucket

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "File deleted successfully",
        "file_key": "uploads/contacts/export-2024.csv"
      }
    }

Transfer file from source to cobalt bucket

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "File transferred successfully",
        "presigned_url": "https://storage.googleapis.com/cobalt-bucket/...",
        "file_key": "uploads/vendors/payment-data.csv",
        "expires_at": "2026-01-20T10:30:00Z"
      }
    }

Read file from SFTP

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "File read successfully",
        "file_name": "contacts-2024.csv",
        "file_size": 245678,
        "content": "base64_encoded_content..."
      }
    }

Delete file from SFTP

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "File deleted successfully",
        "file_path": "/uploads/exports/contacts-2024.csv"
      }
    }

Extract file on SFTP server

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "File extracted successfully",
        "source_path": "/uploads/archive.zip",
        "extract_path": "/downloads/extracted-files/",
        "files_extracted": 15
      }
    }

List files in SFTP folder

    {
      "status": "Success",
      "node_id": "5",
      "node_name": "File Handler",
      "body": {
        "message": "Files listed successfully",
        "folder_path": "/uploads/exports/",
        "files": [
          {
            "name": "contacts-2024-01.csv",
            "size": 125430,
            "modified": "2026-01-15T08:30:00Z"
          },
          {
            "name": "contacts-2024-02.csv",
            "size": 98765,
            "modified": "2026-01-16T14:22:00Z"
          }
        ],
        "total_files": 2
      }
    }

Error Response

    {
      "status": "Errored",
      "node_id": "5",
      "node_name": "File Handler",
      "body": "SFTP connection failed: Authentication failed for user sftp_user"
    }

Adding to your workflow

Add the File Handler node

In the workflow editor, click Add Node and select File Handler from the utility nodes section.

Select an action

Choose the action that matches your use case from the action dropdown.

Configure connection details

For SFTP actions, provide host, port, username, and authentication (password or PEM key). Use environment variables for secure credential management.

Specify file paths

Enter the source and/or destination file paths based on the selected action.

Test the node

Click the Run tab to execute and verify the file operation completes successfully.

Examples

Process SAP Export Files from SFTP

Download daily SAP export files from an SFTP server for processing.Action: Read file from SFTP

Field	Value
Host	`{{env.SAP_SFTP_HOST}}`
Port	`22`
Username	`{{env.SAP_SFTP_USER}}`
Password	`{{env.SAP_SFTP_PASSWORD}}`
File Path	`/exports/sap/vendors-{{today}}.csv`

Use Case: A scheduled workflow runs daily to read vendor export files from SAP’s SFTP server, then processes the data through a Data Converter node before syncing to your application.

Archive NetSuite Reports to Cloud Storage

Transfer NetSuite financial reports from SFTP to Refold bucket for long-term storage.Action: Transfer file from source to cobalt bucketSource File Details:

Field	Value
Protocol	`SFTP`
Host	`sftp.netsuite-exports.com`
Port	`22`
Username	`{{env.NS_SFTP_USER}}`
File Path	`/reports/financial/{{report_date}}.xlsx`
PEM Key	`{{env.NS_SFTP_PEM_KEY}}`

Bucket Object Settings:

Field	Value
Infinite Expiry	Enabled
Preserve Cloud Provider Presigned URL	Disabled

Use Case: After NetSuite generates monthly financial reports, transfer them to cloud storage with permanent retention for compliance purposes.

Batch Process Tipalti Payment Files

List and process all payment files in a Tipalti SFTP folder.Action: List files in SFTP folder

Field	Value
Host	`{{env.TIPALTI_SFTP_HOST}}`
Port	`22`
Username	`{{env.TIPALTI_SFTP_USER}}`
Password	`{{env.TIPALTI_SFTP_PASSWORD}}`
Folder Path	`/outbound/payments/`

Use Case: Use with a Loop node to iterate through all payment files, read each one, process the payments, then delete the processed files.Follow-up Workflow:

List files in SFTP folder → Get file list
Loop node → Iterate through files
Read file from SFTP → Get file content
Process payments → Your business logic
Delete file from SFTP → Clean up processed files

Extract Compressed Vendor Data

Extract a compressed archive containing multiple vendor data files on the SFTP server.Action: Extract file on SFTP server

Field	Value
Host	`sftp.vendor-portal.com`
Port	`22`
Username	`{{env.VENDOR_SFTP_USER}}`
Password	`{{env.VENDOR_SFTP_PASSWORD}}`
File Path	`/incoming/vendor-data-2026-01.tar.gz`
Extract To	`/incoming/extracted/2026-01/`

Use Case: Vendors upload compressed archives containing multiple CSV files. Extract them on the server, then use “List files in SFTP folder” to discover and process each file individually.

Clean Up Processed Files

Delete files from Refold bucket after they’ve been successfully processed.Action: Delete file from Refold bucket

Field	Value
File Key	`{{processed_file.key}}`
File ID	`{{processed_file.etag}}`

Use Case: After successfully syncing file data to SAP, delete the temporary file from the Refold bucket to manage storage costs.

Transfer Files Between SFTP Servers

Move files from a vendor’s SFTP server to your internal SFTP server.Action: Transfer file from source to destinationSource File Details:

Field	Value
Protocol	`SFTP`
Host	`sftp.vendor.com`
Port	`22`
Username	`{{env.VENDOR_USER}}`
Password	`{{env.VENDOR_PASSWORD}}`
File Path	`/outbound/invoices/{{invoice_id}}.pdf`

Destination File Details:

Field	Value
Protocol	`SFTP`
Host	`sftp.internal.yourcompany.com`
Port	`22`
Username	`{{env.INTERNAL_SFTP_USER}}`
PEM Key	`{{env.INTERNAL_SFTP_PEM}}`
File Path	`/incoming/vendor-invoices/{{invoice_id}}.pdf`

Use Case: Automatically transfer vendor invoices from their SFTP server to your internal server for processing by your AP system.

Troubleshooting

SFTP Connection Errors

Problem	Solution
Authentication failed	Verify username and password/PEM key. Check if the account is locked or credentials have expired.
Connection refused	Confirm the host and port are correct. Check if the SFTP server is running and accessible from Refold’s network.
Host key verification failed	The SFTP server’s host key may have changed. Contact your server administrator to verify the new key.
Connection timeout	Check network connectivity. The SFTP server may be behind a firewall blocking Refold’s IP addresses.

File Operation Errors

Problem	Solution
File not found	Verify the file path is correct and the file exists. Check for case sensitivity in file names.
Permission denied	The SFTP user may not have read/write/delete permissions for the specified path. Contact your server administrator.
Disk quota exceeded	The destination server or bucket has reached its storage limit. Free up space or increase quota.
File already exists	The destination file path already contains a file. Delete it first or use a unique file name.

Transfer Errors

Problem	Solution
Transfer timeout	The file may be too large. Check network stability and consider splitting large files.
Invalid URL	For URL protocol, ensure the source URL is publicly accessible and returns the file directly.
Presigned URL expired	Increase the TTL value or use the presigned URL immediately after generation.

Archive Extraction Errors

Problem	Solution
Unsupported format	Only zip, tar, gz, and tgz formats are supported. Convert the archive to a supported format.
Corrupt archive	The archive file may be damaged. Request a new file from the source.
Insufficient space	The extraction destination doesn’t have enough disk space. Free up space or use a different directory.

Store SFTP credentials securely as environment variables under Organization > Settings > Environment Variable rather than hardcoding them in workflows.

Next steps

Loop node

Process multiple files from a directory listing.

Data Converter node

Parse CSV/Excel files after reading.

CSV/Excel node

Handle files smaller than 5MB.

Rule node

Add conditional logic based on file operations.

​When to use

​Common parameters

​Actions

​Output

​Adding to your workflow

​Examples

​Troubleshooting

​Next steps

Loop node

Data Converter node

CSV/Excel node

Rule node

When to use

Common parameters

Actions

Output

Adding to your workflow

Examples

Troubleshooting

Next steps