n8n Binary Data Handling: Read, Write & Process Files in Workflows

Automate File Management with n8n: Mastering Binary Data Handling

In this tutorial, you will learn how to automate file management using n8n by mastering the handling of binary data within your workflows. From fetching files over HTTP to processing email attachments, compressing, decompressing, and uploading files to cloud storage, this guide covers practical steps to build powerful file-based automations using n8n.

Understanding Binary Data in n8n

Binary data in n8n represents any file type you work with: images (PNG, JPG), PDFs, videos, ZIP archives, CSV files, and more. Unlike textual data that appears in JSON or table views, binary data is accessible under the Binary tab in your node's output. This tab allows you to:

• Preview supported file types (e.g., images)
• Download files directly from the workflow editor
• Access file metadata like filename, extension, MIME type, and size

This binary handling capability enables you to automate complex file workflows such as downloading files, modifying them, compressing/decompressing archives, and uploading to cloud services.

For more on testing workflows with sample data, see our guide on Mock Data Testing in n8n.

Step 1: Fetching Files Using HTTP Request Node

To start working with files in n8n, you first need to fetch them. You can use the HTTP Request node to download files from any publicly accessible URL.

Example: Download an Image from a URL

1. Create a new workflow and add a Manual Trigger node.
2. Add an HTTP Request node.
3. Configure the node:
   • Method: GET
   • URL: Paste the direct link to the file (e.g., an image URL).
   • Leave the Authentication, Headers, and Body fields empty if the file is publicly accessible.
4. Execute the node.

After execution, check the Binary tab in the node output:

• You will see the file stored under a binary field (commonly data).
• Use the View button to preview images.
• Use the Download button to save the file locally.

{
  "binary": {
    "data": {
      "fileName": "manali_highway.jpg",
      "fileExtension": "jpg",
      "mimeType": "image/jpeg",
      "data": "<base64-encoded file content>"
    }
  }
}

Step 2: Downloading Email Attachments with Gmail Node

You can automate fetching attachments from your Gmail inbox and process them as binary data.

How to Configure Gmail Node to Download Attachments

1. Add a Gmail node and set the operation to Get Many Messages.
2. Set the Limit to the number of emails you want to fetch (e.g., 1).
3. Disable the Simplify option in the node settings. This exposes more detailed data including attachments.
4. In the Add Options section:
   • Enable Download Attachments.
   • (Optional) Set an Attachment Prefix to identify attachments.
5. Execute the node.

Key Points:

• Attachments are available in the Binary tab, each stored under fields like attachment_0, attachment_1, etc.
• The node output still returns one item per email, with all attachments attached as binary fields within that item.

For systematic debugging of attachment workflows, consider reviewing the Gmail Attachments to Google Drive tutorial.

Step 3: Splitting Multiple Attachments into Separate Items

Since attachments are bundled into one item, use the Split Out Items node to split each attachment into its own item for easier processing.

How to Split Attachments

1. Add a Split Out Items node after the Gmail node.
2. In the Field to Split Out setting, enter the expression:

$binary

3. Execute the node.

Now, each attachment is a separate item, and you can process them individually (e.g., upload, compress, convert).

Step 4: Compressing and Decompressing Files

n8n provides a Compression node that lets you compress multiple files into ZIP or GZIP archives and decompress them back.

Compressing Files

1. Add a Compression node connected to your file source node (e.g., Gmail or Split Out Items).
2. Set Operation to Compress.
3. Provide a comma-separated list of file names to compress (e.g., attachment_0,attachment_1,attachment_2).
   • Note: The node expects file names explicitly; it does not accept $binary directly.
   • To dynamically generate this list, use a Function or Code node to output the list.
4. Choose output format: zip or gzip.
5. Enter the output file name, e.g., attachments.zip.
6. Specify the field where the compressed file should be stored (usually data).
7. Execute the node.

Decompressing Files

1. Add another Compression node.
2. Set Operation to Decompress.
3. Set the input binary field (usually data).
4. Optionally set an output prefix for decompressed files (e.g., file_).
5. Execute the node.

Splitting Decompressed Files

Decompressed files are returned as multiple files in binary fields but within a single item. Use the Split Out Items node again with $binary to split them into separate items.

Refer to the n8n Merge node documentation for advanced techniques on combining and splitting data streams in workflows.

Step 5: Uploading Files to Cloud Storage (Google Drive Example)

Once you have your files ready, you can upload them to cloud storage providers like Google Drive, OneDrive, AWS S3, etc.

Uploading Files to Google Drive

1. Add a Google Drive node.
2. Set Operation to Upload File.
3. Set the Binary Property to the field containing your file data (e.g., data or file_0).
4. Enter the File Name. You can set a static name or use an expression to dynamically name files:

{{$json["fileName"] || "default_name.txt"}}

5. Select the Parent Folder in Google Drive.
6. Execute the node.

Important Execution Setting

• By default, n8n executes a node once per input item.
• If you want to upload multiple files in one execution, set the node to Execute Once in the node settings.
• Alternatively, handle multiple files using the split node and let the upload node process each file individually.

Additional Useful Nodes for File Handling in n8n

• Read Binary File / Write Binary File: Access files from or save files to the local disk (only works if n8n is self-hosted).
• Convert to File: Convert JSON data to a binary file for logging or uploading.
• Extract from File: Convert binary file content back to JSON.
• FTP Node: Upload, download, rename, delete, or list files on FTP/SFTP servers.
• FileMaker Node: Integrate with FileMaker databases that may handle files.
• Compression Node: As covered, compress and decompress files.

See the official n8n documentation on file handling for detailed configuration options.

Common Mistakes and Troubleshooting

• No Binary Tab Visible: Ensure that the node is configured to download files or attachments (e.g., disable Simplify in Gmail node and enable Download Attachments).
• Compression Node Not Compressing Multiple Files: The node requires explicit file names; $binary expression alone won’t work. Use a Code node to generate a comma-separated string of file names.
• Upload Node Fails on Multiple Files: Understand the execution mode—either set node to run once or split items before uploading.
• Unsupported File Preview: Not all file types can be previewed in n8n (e.g., PDFs). Use the download option to view them locally.
• Local File Access: Reading or writing local files requires a self-hosted n8n instance; cloud instances cannot access your local filesystem.

For mastering error patterns and handling issues gracefully, check out Master Error Handling in n8n.

Cheat Sheet: Key Expressions and Nodes for File Handling

Summary

By mastering binary data handling in n8n, you unlock the power to automate complex file management workflows. Whether downloading remote files, processing email attachments, compressing archives, or uploading to cloud storage, n8n’s nodes and binary data handling features give you full control over your file automation pipelines.

For deeper understanding and examples, refer to the n8n documentation on Binary Data and other relevant nodes.

As shown in the video above, these techniques enable you to build robust, scalable workflows to automate your file handling processes efficiently.