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/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts
- packages/core/src/utils/convert-binary-data.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
- packages/testing/playwright/tests/e2e/api/binary-data-xss.spec.ts
Binary Data Handling in n8n encompasses the methods and services used to process, store, and retrieve non-textual data (such as images, PDFs, or spreadsheets) throughout a workflow execution. Documents and files are treated as binary objects that must be explicitly managed to prevent data loss or memory exhaustion. The system supports multiple storage modes, including in-memory storage (default) and filesystem-based storage to handle larger files efficiently.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
Core Components and Storage Modes
The system operates primarily through a BinaryDataService which abstracts the underlying storage mechanism. There are two primary modes for handling binary data:
- Default Mode (Memory): Binary data is converted to Base64 strings and stored within the workflow execution's JSON object. This is suitable for small files but can lead to memory issues with large datasets.
- Filesystem Mode: Binary data is stored on disk at a configured
localStoragePath. The JSON object contains a reference (ID) to the file rather than the data itself.
Binary Data Metadata Structure
The IBinaryData interface defines the properties used to describe a file within the system:
| Field | Type | Description |
|---|---|---|
data | string | The actual data (Base64) or a storage manager reference (e.g., filesystem-v2). |
mimeType | string | The IANA media type (e.g., application/pdf, image/png). |
id | string | Unique identifier for the binary object in storage. |
fileName | string | The original name of the file. |
fileExtension | string | The file extension (e.g., txt, jpg). |
fileSize | string | Size of the file in bytes. |
Sources: packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:80-95, packages/core/src/utils/convert-binary-data.ts:80-90
Data Flow and Conversion
When a node executes, it produces output that can include binary data. The system manages the transition of this data through the convertBinaryData utility, which ensures that binary objects are correctly stored based on the active storage mode.
The diagram above shows how binary data is intercepted after node execution to be moved into the standardized binaries location within the JSON object if "combined" mode is enabled.
Sources: packages/core/src/utils/convert-binary-data.ts:25-70
Retrieval Logic
Nodes retrieve binary data using helper functions that resolve data paths based on the execution mode (Separate vs. Combined).
- Separate Mode: Binary data is located in the
item.binaryproperty. - Combined Mode: Binary data is embedded within the
item.jsonproperty, often under a specific key likebinaries.
Key Helper Functions
The system provides several core functions via the execution context to manipulate binary data:
| Function | Description |
|---|---|
prepareBinaryData | Takes a Buffer or Stream, detects MIME types/extensions, and stores it in the configured storage manager. |
getBinaryDataBuffer | Resolves a binary property name or object to a Node.js Buffer. |
setBinaryDataBuffer | Updates or creates a binary object from a Buffer and assigns it to a workflow/execution context. |
detectBinaryEncoding | Analyzes a Buffer to determine the character encoding (e.g., UTF-8, Shift-JIS). |
assertBinaryData | Validates that a specific input property contains valid IBinaryData and throws an error if missing. |
Sources: packages/core/src/execution-engine/node-execution-context/utils/binary-helper-functions.ts, packages/core/src/execution-engine/node-execution-context/utils/tests/binary-helper-functions.test.ts:500-600
Security: XSS Prevention
Binary data serving includes protections against Cross-Site Scripting (XSS). Specifically, when serving HTML binary data that lacks a fileName in its metadata, the system is designed to prevent browsers from rendering the content inline as active HTML, which could otherwise lead to same-origin JavaScript execution.
Sources: packages/testing/playwright/tests/e2e/api/binary-data-xss.spec.ts:15-30
Best Practices for Workflow Development
Referencing Binary Data
When referencing data in expressions, the syntax depends on the preceding node's naming convention:
- Standard:
{{ $binary.property_name }} - Specific Node (e.g., Gmail):
{{ $('Gmail Trigger').item.binary.attachment_0 }}
Memory and Persistence
- Batching: For workflows processing large volumes of files, use the Split In Batches node to avoid crashing the instance due to memory limits.
- Data Loss: Binary data is often dropped by default in transformation nodes (like Set or Code). Developers must enable "Include Other Input Fields" to preserve binary data through the pipeline.
- Type Checking: Always verify the file type (MIME type or extension) before passing data to extraction nodes like Extract From File to prevent execution errors.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
Summary
Binary Data Handling in n8n is a robust system designed to balance performance and flexibility. By abstracting storage into a service layer, the engine can switch between memory-efficient disk storage and convenient in-memory Base64 handling. Developers interacting with the system must be mindful of data preservation across nodes and leverage the provided helper functions for safe data retrieval and transformation.