n8n Binary Data: A Complete Guide to Handling Files in 2026

Automating file-based tasks is a core strength of n8n, but it requires a solid understanding of n8n binary data. Whether you're processing CSV reports, generating PDF invoices, or handling user-uploaded images, you're working with binary data. This guide provides a complete overview of how n8n manages files, giving you the practical steps to build robust file-based automations for any use case in 2026.

What Exactly Is Binary Data in n8n?

In n8n, a "file" isn't passed around your workflow like it is on your desktop. Instead, n8n uses a special, efficient system. When a file is introduced into a workflow (e.g., from an HTTP download or a webhook), n8n saves it to the storage of your instance and creates a reference to it. This reference is called "binary data".

This binary data reference is attached to the JSON item passing through your workflow. It appears as a special object, typically under a property named data. Here’s what it looks like in the n8n interface:

{
  "json": {
    "fileName": "report.xlsx",
    "type": "customer-data"
  },
  "binary": {
    "data": {
      "id": "f4e5a5a1-d227-4c74-85d1-9d1e57c2c62c",
      "fileName": "report.xlsx",
      "fileType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "fileSize": 8452
    }
  }
}

The binary object contains one or more properties (in this case, one named data) that hold the metadata about the file stored on the backend. The actual file content is not in the JSON, which keeps the workflow data light and fast. When another node needs to use the file, it uses this reference to access it.

How to Receive Binary Data in Workflows

Your workflows can get files from multiple sources. Here are the most common methods:

1. Webhook Node

   The Webhook node is a primary entrypoint for files. When you send a multipart/form-data request to a webhook URL, n8n automatically parses the file, saves it, and creates the binary data reference.

   • Method: POST
   • Body Type: Multipart/Form-Data
   • Configuration: No special configuration is needed in the Webhook node. Just ensure your sending application uses the correct content type.
2. Read Binary File Node

   This node reads a file directly from the filesystem of the server running n8n. You provide the path to the file, and the node outputs an item with the corresponding binary data.

   • Use Case: Processing files that are placed on a specific server directory via SCP/FTP or other processes.
   • Note: This requires access to the underlying filesystem, which is straightforward on managed solutions like n8nautomation.cloud where your environment is dedicated.
3. HTTP Request Node

   When you use the HTTP Request node to download a file from a URL, you can configure it to output binary data.

   • Mode: Get
   • Response Format: "File"
   • How it works: n8n makes the request, downloads the response body directly to a file, and outputs the binary data reference for use in subsequent nodes. This is perfect for grabbing reports, images, or assets from APIs.

Manipulating and Converting Binary Data

Once you have a file in your workflow, you often need to do something with it. n8n provides several nodes for this purpose.

• Spreadsheet File Node: The most powerful node for handling structured n8n binary data. It can read binary data representing an Excel (.xls, .xlsx) or CSV file and convert its rows into individual JSON items for processing. You can also use it in reverse to generate a spreadsheet from JSON data.
• Move Binary Data Node: A utility node that lets you move or copy binary data between properties. For instance, if an HTTP Request node downloads a file into a property named data, you can use this node to rename it to invoicePDF for clarity.
• Convert to/from Base64: Some APIs don't accept multipart file uploads but require files to be sent as Base64-encoded strings. The Move Binary Data node has a "Convert to Base64" option for this. Similarly, the Static Data node can convert a Base64 string back into binary data.
• Code Node: For ultimate flexibility, the Code node gives you direct access to the binary data buffer. You can read the file content, modify it, or perform complex parsing logic that isn't available in other nodes.

  
  // Access the binary data buffer from an input item
  const binaryData = await getBinaryData(0, 'data');
  
  // Example: Convert buffer to a string
  const fileContent = binaryData.toString('utf8');
  
  // You can now manipulate 'fileContent'
  return { json: { content: fileContent } };
      

Use Case: Processing a Webhook File Upload

Let’s walk through a common scenario: a user submits a form with an Excel file, and we want to process each row in the sheet.

1. Webhook Node (Trigger):
   • Set the "HTTP Method" to POST.
   • The webhook URL is now ready to accept file uploads. Test it using a tool like Postman or Insomnia, sending a a multipart/form-data request with a file attached to a field (e.g., named 'fileUpload').
2. Spreadsheet File Node:
   • Connect it after the Webhook node.
   • Set "Operation" to "Read".
   • Set "Binary Property" to the name of the form field you used (e.g., fileUpload). This tells the node which binary data to read.
   • The node will execute and convert each row from the spreadsheet into a separate n8n item.
3. Process Each Row (e.g., IF or Switch Node):
   • You can now add any number of nodes to process the data from each row. You could add them to a Google Sheet, update a CRM, or send a custom email.
4. Respond to Webhook Node:
   • At the end of your workflow, use this node to confirm that the file was received and is being processed. This provides immediate feedback to the system that called the webhook.

Writing and Sending Binary Data

Just as you can receive files, you can also send them. This is how you deliver reports, save generated assets, and complete file-based workflows.

• Write Binary File Node: This is the opposite of the Read Binary File node. It takes an item with binary data and writes it to a specified path on the n8n server's filesystem. Useful for creating backups or staging files for other processes.
• HTTP Request Node (Upload):
  1. Set "Method" to POST or PUT.
  2. Set "Body Content Type" to Multipart/Form-Data.
  3. In the "Body" section, create a field and set its value using an expression to the binary property name (e.g., {{ $binary.data.fileName }} is not what you want, you need to point to the property itself).
  4. In the options for that field, toggle "This is a file" to ON and specify the "Property Name" of the binary data (e.g., data).
• Email/Chat Nodes (Attachments): Most nodes that support sending messages also support attachments. For example, in the SendGrid or Brevo nodes, there's an "Attachments" field where you can simply enter the name of the binary property (e.g., invoicePDF). The node handles the rest.

Best Practices for Handling Files

Working with files can be resource-intensive. Follow these tips to build efficient and reliable workflows.

• Error Handling: Files can be corrupt, in the wrong format, or too large. Always add error handling branches to your workflows to catch issues gracefully. Use the "Continue on Fail" setting in nodes that might fail.
• Manage Memory: Avoid reading very large files entirely into memory with a Code node if possible. Use streaming nodes or batching (like the Spreadsheet File node provides) whenever you can. Running on a dedicated server from n8nautomation.cloud gives you guaranteed resources to handle larger files without impacting other users.
• Clean Up Data: After you've processed a file, you may not need the binary data anymore. Use a `Set` node to remove the binary property if your workflow continues, which can reduce the data passed between steps.
• Be Specific with Naming: Use the "Move Binary Data" node to give your file properties meaningful names (e.g., `userAvatar`, `monthlyReport`, `signedContract`). This makes your workflows much easier to read and debug.

By mastering how n8n handles binary data, you unlock a massive range of automation possibilities. From simple file downloads to complex ETL pipelines, the principles are the same: receive, process, and send. Now you have the blueprint to do it effectively.