Binary Data Handling
Relevant source files
The following files were used as context for generating this wiki page:
- packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts
- packages/cli/src/controllers/tests/binary-data.controller.test.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts
- packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts
- packages/nodes-base/nodes/WriteBinaryFile/WriteBinaryFile.node.json
- packages/nodes-base/nodes/ReadBinaryFile/ReadBinaryFile.node.json
Binary data is a fundamental concept in n8n, representing files such as images, PDFs, spreadsheets, and other non-textual data that flows through workflows. The system provides a robust set of services and helper functions to create, manage, store, and retrieve this data. Proper handling is crucial to prevent data loss and manage system resources, especially when dealing with large files or high-volume workflows.
The binary data handling system is designed to be flexible, with configurable storage backends (in-memory or filesystem) and a consistent interface for nodes to interact with file data. This ensures that binary data is preserved and accessible throughout the different stages of a workflow execution, from triggers to data transformation and final output.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts:1-10, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts:16-18
Architecture Overview
The binary data system is centered around the BinaryDataService, which abstracts the storage and retrieval logic. Nodes interact with this service via a set of BinaryHelperFunctions provided within the node execution context. The service delegates the actual storage operations to a configured manager, such as the FileSystemManager.
This diagram shows the high-level architecture of binary data handling during node execution.
Storage Modes
n8n supports different modes for storing binary data, configured via N8N_DEFAULT_BINARY_DATA_MODE.
- Default (
default): Stores binary data in-memory as Base64 encoded strings. This is simple but can consume significant memory with large files. - Filesystem (
filesystem): Stores binary data on the local disk and references it by a unique ID. This is recommended for handling large files to avoid memory issues.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts:31-32, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:40-42, 73-75
Data Representation: IBinaryData
All binary data in n8n is represented by the IBinaryData interface. This object contains metadata about the file but does not hold the data itself directly unless using the default storage mode.
| Property | Type | Description |
|---|---|---|
id | string | A unique identifier for the binary data, prefixed with the storage mode (e.g., filesystem-v2:uuid). |
data | string | In default mode, this holds the Base64-encoded data. In filesystem mode, it holds the storage manager identifier (e.g., filesystem-v2). |
mimeType | string | The MIME type of the file (e.g., application/pdf). |
fileName | string | The name of the file (e.g., invoice.pdf). |
fileExtension | string | The file extension (e.g., pdf). |
fileType | string | A simplified file type category (e.g., pdf, text). |
fileSize | number | The size of the file in bytes. (Available from metadata). |
directory | string | The original directory or URL of the file, if available. |
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:10-18, 195-201, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:410-422
Core Helper Functions
Nodes are provided with a suite of helper functions to manage binary data. These are available on the execution context (this.helpers).
prepareBinaryData
This function is the primary way to create an IBinaryData object from a Buffer or Readable stream. It automatically detects the MIME type, extracts the filename, and stores the data using the configured BinaryDataService.
The following diagram illustrates the process of preparing binary data.
assertBinaryData
A utility to safely retrieve binary data from a node's input. It can take either a property name (string) to look up in the input item's binary object or an IBinaryData object directly. It throws a NodeOperationError if the specified binary data is not found, providing clear feedback to the user.
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:80-129, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:511-530
getBinaryDataBuffer
This function retrieves the raw Buffer for a given IBinaryData object or a property name from the input. It abstracts away the storage mechanism, fetching the data from memory or the filesystem as needed.
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:135-156, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:114-123
setBinaryDataBuffer
Stores a Buffer or Readable stream and returns a corresponding IBinaryData object. This function is used internally by prepareBinaryData but can also be used directly for more control.
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:165-177
binaryToString
Converts a binary buffer or stream into a string. It can automatically detect the character encoding using chardet if one is not provided, but an explicit encoding is recommended for accuracy.
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:31-37, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:223-229
createBinarySignedUrl
Generates a temporary, secure URL to access a binary file. This is useful for integrations that need to provide a public-facing link to a file stored in n8n. The URL is signed with a JWT token that expires after a configured duration.
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts:286-289, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:681-698
API Endpoint: /binary-data
n8n exposes a REST API endpoint to retrieve binary data. This is used, for example, to render previews in the UI or to serve files via signed URLs.
The BinaryDataController handles these requests.
This sequence diagram shows how a client retrieves a file via the signed URL.
Endpoint Parameters
| Parameter | Description | Example |
|---|---|---|
id | The unique ID of the binary data (e.g., filesystem-v2:xyz). | filesystem-v2:abc-123 |
action | view for inline display or download to trigger a file download. | download |
fileName | Overrides the filename for the Content-Disposition header. | report.pdf |
mimeType | Overrides the Content-Type header. | image/jpeg |
token | A signed JWT for accessing data via the /binary-data/signed endpoint. | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
Sources: packages/cli/src/controllers/tests/binary-data.controller.test.ts:32-35, 114-121, 143-152
Security
The controller includes several security checks:
- It validates that the binary data ID is well-formed and has a valid mode prefix.
- It prevents the inline viewing (
viewaction) of potentially malicious file types liketext/html. - The
getSignedendpoint relies on JWT validation to ensure the request is authorized and not expired.
Sources: packages/cli/src/controllers/tests/binary-data.controller.test.ts:38-51, 155-166, 222-231
Best Practices in Workflows
Properly managing binary data is essential for creating reliable workflows.
Referencing Binary Data
To use binary data from a previous node, use an expression that points to the binary property of an item. The property name depends on the node that generated the file.
- Expression Syntax:
{{ $('Node Name').item.binary.property_name }} - Example (Gmail attachment):
{{ $('Gmail Trigger').item.binary.attachment_0 }} - Example (Webhook file):
{{ $('Webhook').item.binary.data }}
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts:17-23, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts:21-27
Preserving Binary Data
Many nodes that transform data (like Set or Code) do not automatically pass binary data through. This is a common source of data loss.
- Solution 1: In nodes like
Set, enable the "Include Other Input Fields" option. - Solution 2: Process the binary data in a separate, parallel branch and rejoin it later using a
Mergenode.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts:34-36, 52-54, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts:29-35
Large File Handling
Processing many large files can lead to high memory usage and cause workflows to crash.
- Use Filesystem Mode: For self-hosted instances, set the environment variable
N8N_DEFAULT_BINARY_DATA_MODE=filesystemto store binary data on disk instead of in memory. - Process in Batches: Use the
Split In Batchesnode to process files in smaller chunks, reducing the memory footprint at any given time.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-extraction.ts:28-32, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts:211-215
Conclusion
The binary data handling system in n8n is a core component that enables powerful file-based automations. It provides a clear abstraction through the BinaryDataService and a set of convenient helper functions for node developers. For workflow creators, understanding how to reference, preserve, and manage binary data—especially large files—is key to building robust and scalable workflows. By following best practices, developers and users can avoid common pitfalls like data loss and memory overload.