> ## Documentation Index
> Fetch the complete documentation index at: https://cobalt-55-abhishek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Handler node

> Transfer, read, delete, and manage files across SFTP servers and cloud storage buckets

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

<Info>This node is recommended for files **greater than 5MB**. For smaller files, use the [CSV/Excel node](/v3/platform/concepts/workflows/nodes/csv-excel) instead.</Info>

## Common parameters

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

<AccordionGroup>
  <Accordion title="SFTP Connection Parameters">
    <ParamField path="Host" type="string" required>
      SFTP server hostname or IP address. Example: `sftp.example.com` or `{{config.sftp_host}}`
    </ParamField>

    <ParamField path="Port" type="integer" required>
      SFTP server port. Default: `22`
    </ParamField>

    <ParamField path="Username" type="string" required>
      SFTP username for authentication. Supports dynamic variables. Example: `sftp_user` or `{{env.SFTP_USERNAME}}`
    </ParamField>

    <ParamField path="Password" type="string">
      Password for SFTP authentication. Use this if not using PEM key authentication. Supports dynamic variables. Example: `{{env.SFTP_PASSWORD}}`
    </ParamField>

    <ParamField path="PEM Key" type="string">
      SSH private key in PEM format for key-based authentication. Use this if not using password authentication. Supports dynamic variables.
    </ParamField>

    <ParamField path="PEM Key Passphrase" type="string">
      Passphrase for the PEM private key, if the key is passphrase-protected. Supports dynamic variables.
    </ParamField>

    <Tip>Store SFTP credentials as environment variables under [**Organization > Settings > Environment Variable**](/v3/platform/platform-settings/workspace-settings/environment-variables) for secure, reusable configuration.</Tip>
  </Accordion>

  <Accordion title="Source/Destination File Details">
    Used in transfer actions to specify file locations.

    <ParamField path="Protocol" type="dropdown" required>
      The protocol for accessing the file. The **source** supports `SFTP` or `URL`. The **destination** supports `SFTP` only.
    </ParamField>

    **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):**

    <ParamField path="URL" type="string" required>
      Public URL of the file to transfer. Example: `https://example.com/files/export.csv` or `{{previous_node.file_url}}`
    </ParamField>
  </Accordion>
</AccordionGroup>

## Actions

<AccordionGroup>
  <Accordion title="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.

    <ParamField path="File Key" type="string" required>
      The file path/name in the bucket. Example: `uploads/contacts/export-2024.csv` or `{{uploaded_file.key}}`
    </ParamField>

    <ParamField path="File ID" type="string">
      The file identifier (ETag for S3/MinIO, generation for GCP). Use this for version-specific deletion. Example: `33a64df551425fcc55e4d42a148795d9f25f89d4`
    </ParamField>
  </Accordion>

  <Accordion title="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.

    <ParamField path="Source File Details" type="object" required>
      Configuration for the source file location. Select protocol (SFTP or URL) and provide corresponding connection details.
    </ParamField>

    <ParamField path="Destination File Details" type="object" required>
      Configuration for the destination file location. Select protocol (SFTP or URL) and provide corresponding connection details.
    </ParamField>

    **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 |
  </Accordion>

  <Accordion title="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.

    <ParamField path="Source File Details" type="object" required>
      Configuration for the source file. The source protocol is `SFTP`; provide the SFTP connection details.
    </ParamField>

    <ParamField path="Bucket Object Settings" type="object">
      Configuration for the uploaded file in the bucket.
    </ParamField>

    **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.           |
  </Accordion>

  <Accordion title="Read file from SFTP">
    Reads and downloads a file from an SFTP server. The file content is returned for use in subsequent workflow steps.

    <ParamField path="Host" type="string" required>
      SFTP server hostname. Example: `sftp.example.com`
    </ParamField>

    <ParamField path="Port" type="integer" required>
      SFTP server port. Default: `22`
    </ParamField>

    <ParamField path="Username" type="string" required>
      SFTP username for authentication.
    </ParamField>

    <ParamField path="Password" type="string">
      Password for SFTP authentication (if not using PEM key).
    </ParamField>

    <ParamField path="File Path" type="string" required>
      Full path to the file on the SFTP server. Example: `/uploads/exports/contacts-2024.csv`
    </ParamField>

    <ParamField path="PEM Key" type="string">
      SSH private key in PEM format for key-based authentication (if not using password).
    </ParamField>

    <ParamField path="PEM Key Passphrase" type="string">
      Passphrase for the PEM key (if passphrase-protected).
    </ParamField>
  </Accordion>

  <Accordion title="Delete file from SFTP">
    Deletes a file from an SFTP server.

    <ParamField path="Host" type="string" required>
      SFTP server hostname. Example: `sftp.example.com`
    </ParamField>

    <ParamField path="Port" type="integer" required>
      SFTP server port. Default: `22`
    </ParamField>

    <ParamField path="Username" type="string" required>
      SFTP username for authentication.
    </ParamField>

    <ParamField path="Password" type="string">
      Password for SFTP authentication (if not using PEM key).
    </ParamField>

    <ParamField path="File Path" type="string" required>
      Full path to the file to delete. Example: `/uploads/exports/contacts-2024.csv`
    </ParamField>

    <ParamField path="PEM Key" type="string">
      SSH private key in PEM format for key-based authentication (if not using password).
    </ParamField>

    <ParamField path="PEM Key Passphrase" type="string">
      Passphrase for the PEM key (if passphrase-protected).
    </ParamField>
  </Accordion>

  <Accordion title="Extract file on SFTP server">
    Extracts a compressed archive file directly on the SFTP server. Supports zip, tar, gz, and tgz formats.

    <ParamField path="Host" type="string" required>
      SFTP server hostname. Example: `sftp.example.com`
    </ParamField>

    <ParamField path="Port" type="integer" required>
      SFTP server port. Default: `22`
    </ParamField>

    <ParamField path="Username" type="string" required>
      SFTP username for authentication.
    </ParamField>

    <ParamField path="Password" type="string">
      Password for SFTP authentication (if not using PEM key).
    </ParamField>

    <ParamField path="File Path" type="string" required>
      Full path to the compressed file. Example: `/uploads/archive.zip`
    </ParamField>

    <ParamField path="Extract To" type="string">
      Destination directory for extracted files. Example: `/downloads/extracted-files/`
    </ParamField>

    <ParamField path="PEM Key" type="string">
      SSH private key in PEM format for key-based authentication (if not using password).
    </ParamField>

    <ParamField path="PEM Key Passphrase" type="string">
      Passphrase for the PEM key (if passphrase-protected).
    </ParamField>

    <Info>Supported archive formats: `zip`, `tar`, `gz`, `tgz`</Info>
  </Accordion>

  <Accordion title="List files in SFTP folder">
    Lists all files in a specified folder on an SFTP server. Use this to discover files for batch processing.

    <ParamField path="Host" type="string" required>
      SFTP server hostname. Example: `sftp.example.com`
    </ParamField>

    <ParamField path="Port" type="integer" required>
      SFTP server port. Default: `22`
    </ParamField>

    <ParamField path="Username" type="string" required>
      SFTP username for authentication.
    </ParamField>

    <ParamField path="Password" type="string">
      Password for SFTP authentication (if not using PEM key).
    </ParamField>

    <ParamField path="Folder Path" type="string" required>
      Path to the folder to list. Example: `/uploads/exports/`
    </ParamField>

    <ParamField path="PEM Key" type="string">
      SSH private key in PEM format for key-based authentication (if not using password).
    </ParamField>

    <ParamField path="PEM Key Passphrase" type="string">
      Passphrase for the PEM key (if passphrase-protected).
    </ParamField>
  </Accordion>

  <Accordion title="Move file to Refold bucket (deprecated)">
    <Warning>This action is **deprecated** and will be removed in a future version. Use **Transfer file from source to cobalt bucket** instead.</Warning>

    Moves a file from a URL to the Refold bucket.

    <ParamField path="Source File URL" type="string" required>
      Public URL of the file to move. Example: `https://example.com/files/document-2024.pdf`
    </ParamField>

    <ParamField path="TTL" type="integer">
      Time-to-live in seconds for the file in the bucket. Example: `86400` (24 hours)
    </ParamField>

    <ParamField path="File Name" type="string">
      Destination path/name in the bucket. Example: `uploads/documents/document-2024.pdf`
    </ParamField>

    <ParamField path="Presign URL" type="toggle">
      When enabled, returns a presigned URL for the uploaded file.
    </ParamField>

    <ParamField path="Presigned URL TTL" type="integer">
      Time-to-live in seconds for the presigned URL. Example: `3600` (1 hour)
    </ParamField>
  </Accordion>
</AccordionGroup>

## Output

<AccordionGroup>
  <Accordion title="Delete file from Refold bucket">
    ```json theme={null}
        {
          "status": "Success",
          "node_id": "5",
          "node_name": "File Handler",
          "body": {
            "message": "File deleted successfully",
            "file_key": "uploads/contacts/export-2024.csv"
          }
        }
    ```
  </Accordion>

  <Accordion title="Transfer file from source to cobalt bucket">
    ```json theme={null}
        {
          "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"
          }
        }
    ```
  </Accordion>

  <Accordion title="Read file from SFTP">
    ```json theme={null}
        {
          "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..."
          }
        }
    ```
  </Accordion>

  <Accordion title="Delete file from SFTP">
    ```json theme={null}
        {
          "status": "Success",
          "node_id": "5",
          "node_name": "File Handler",
          "body": {
            "message": "File deleted successfully",
            "file_path": "/uploads/exports/contacts-2024.csv"
          }
        }
    ```
  </Accordion>

  <Accordion title="Extract file on SFTP server">
    ```json theme={null}
        {
          "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
          }
        }
    ```
  </Accordion>

  <Accordion title="List files in SFTP folder">
    ```json theme={null}
        {
          "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
          }
        }
    ```
  </Accordion>

  <Accordion title="Error Response">
    ```json theme={null}
        {
          "status": "Errored",
          "node_id": "5",
          "node_name": "File Handler",
          "body": "SFTP connection failed: Authentication failed for user sftp_user"
        }
    ```
  </Accordion>
</AccordionGroup>

## Adding to your workflow

<Steps>
  <Step title="Add the File Handler node">
    In the workflow editor, click **Add Node** and select **File Handler** from the utility nodes section.
  </Step>

  <Step title="Select an action">
    Choose the action that matches your use case from the action dropdown.
  </Step>

  <Step title="Configure connection details">
    For SFTP actions, provide host, port, username, and authentication (password or PEM key). Use environment variables for secure credential management.
  </Step>

  <Step title="Specify file paths">
    Enter the source and/or destination file paths based on the selected action.
  </Step>

  <Step title="Test the node">
    Click the **Run** tab to execute and verify the file operation completes successfully.
  </Step>
</Steps>

## Examples

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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 bucket

    **Source 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.
  </Accordion>

  <Accordion title="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:**

    1. List files in SFTP folder → Get file list
    2. Loop node → Iterate through files
    3. Read file from SFTP → Get file content
    4. Process payments → Your business logic
    5. Delete file from SFTP → Clean up processed files
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Transfer Files Between SFTP Servers">
    Move files from a vendor's SFTP server to your internal SFTP server.

    **Action:** Transfer file from source to destination

    **Source 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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.             |
  </Accordion>

  <Accordion title="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.                       |
  </Accordion>

  <Accordion title="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.                 |
  </Accordion>

  <Accordion title="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. |
  </Accordion>
</AccordionGroup>

<Tip>Store SFTP credentials securely as environment variables under [**Organization > Settings > Environment Variable**](/v3/platform/platform-settings/workspace-settings/environment-variables) rather than hardcoding them in workflows.</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Loop node" icon="repeat" href="/v3/platform/concepts/workflows/nodes/loop">
    Process multiple files from a directory listing.
  </Card>

  <Card title="Data Converter node" icon="file-import" href="/v3/platform/concepts/workflows/nodes/csv-excel">
    Parse CSV/Excel files after reading.
  </Card>

  <Card title="CSV/Excel node" icon="file-csv" href="/v3/platform/concepts/workflows/nodes/csv-excel">
    Handle files smaller than 5MB.
  </Card>

  <Card title="Rule node" icon="bolt" href="/v3/platform/concepts/workflows/nodes/rule">
    Add conditional logic based on file operations.
  </Card>
</CardGroup>