Binary Data Management

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-transformation.ts
• packages/nodes-base/utils/tests/binary.test.ts
• packages/frontend/editor-ui/src/features/ndv/runData/components/BinaryDataViewModal.test.ts
• packages/nodes-base/TESTING_PROMPT.md

Binary Data Management refers to the systems and patterns used to handle non-textual files—such as PDFs, images, spreadsheets, and audio—within n8n workflows. Unlike JSON data which is processed as text, binary data requires specialized storage modes and extraction techniques to preserve file integrity while enabling data transformation.

Proper management ensures that files are correctly ingested, preserved through node executions, and converted to structured JSON when necessary for analysis or storage in external databases.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts

Architecture and Data Flow

Binary data follows a specific lifecycle from ingestion to final destination. The core architecture for handling documents involves capturing binary data, extracting its contents, and then transforming that content for downstream use.

Document Processing Pattern

The standard flow for binary data follows these steps:

1. Trigger: Capture incoming files via Email, Webhooks, or cloud storage.
2. Capture: Files are stored as binary properties (e.g., attachment_0, data).
3. Extraction: Nodes like "Extract from File" convert binary content into JSON.
4. Preservation: Specialized branching or node configurations prevent the loss of binary data during JSON transformations.

Storage and Optimization

n8n provides different modes for storing binary data depending on the environment and performance requirements.

Filesystem vs. Memory

For high-volume processing or large files, you can enable filesystem mode to store data on disk instead of system RAM.

• Memory Mode: Default mode. Faster but risks crashing the instance with large files.
• Filesystem Mode: Enabled via N8N_DEFAULT_BINARY_DATA_MODE=filesystem. Recommended for self-hosted instances handling large datasets.

Memory Optimization Strategies

• Process files sequentially or in small batches using the Split In Batches node.
• Drop unnecessary binary data properties after extraction to free up memory.
• Use sub-workflows to delegate heavy processing tasks.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts:21-28, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:68-75

Preservation and Referencing

Binary data is often lost when intermediate nodes (like "Set" or "Code") output new JSON data without explicitly carrying over binary properties.

Preservation Techniques

1. Parallel Branches: One branch processes data while the other preserves the original file. Use a Merge node in "Pass Through" mode to rejoin them.
2. Node Configuration: In the Edit Fields (Set) node, enable the "Include Other Input Fields" option to keep existing binary properties.
3. Code Node: Explicitly copy items[0].binary to the output in custom JavaScript.

Referencing Binary Data

You reference binary properties using expressions. The property name depends on the previous node's configuration (e.g., Gmail uses attachment_0).

Source Node	Expression Example
Gmail Trigger	{{ $('Gmail Trigger').item.binary.attachment_0 }}
Webhook	{{ $('Webhook').item.binary.data }}
Direct Previous	{{ $binary.property_name }}

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:48-65, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-extraction.ts:13-20

Extraction and Conversion

Nodes must explicitly convert binary data to JSON for logical processing.

Extraction Node (Extract from File)

This node supports multiple operations based on the file type. You must verify the file type (via MIME type or extension) before selecting an operation.

File Type	Operation
PDF	Extract from PDF
Excel	Extract from MS Excel (.xlsx, .xls)
Word	Extract from MS Word (.docx)
CSV	Extract from CSV
Scanned Images	Use OCR (AWS Textract, Mindee, or OCR.space)

Conversion Logic (Utility Functions)

The system uses internal utilities to route and serialize binary data during execution.

// Example: Routing binary properties in the nodes-base package
// Sources: packages/nodes-base/utils/__tests__/binary.test.ts:258-270
const { json, binary } = await routeBinaryProperties.call(executeFunctions, {
    name: 'document',
    file: Buffer.from('file-bytes'),
});
// Result: 'json' contains 'name', 'binary' contains the processed 'file' property

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts:79-106, packages/nodes-base/utils/tests/binary.test.ts:258-270

Client-Side Visualization

The n8n editor provides a Binary Data View Modal to preview binary content directly within the UI.

File Type Detection logic

The frontend detects the appropriate viewer based on the mimeType.

• Images: Renders <img> tags for formats like image/png or image/jpeg.
• Video/Audio: Renders HTML5 <video> or <audio> elements with appropriate source types.
• PDF: Renders an <iframe> using a generated Object URL.
• Text/JSON: Fetches content and renders it in a <pre> block or specialized code viewer.

Testing Binary Operations

Testing nodes that handle binary data requires mocking the n8n-workflow binary helpers.

Common Mocks

• helpers.prepareBinaryData: Mocks the conversion of a Buffer into n8n's internal binary format.
• helpers.assertBinaryData: Validates that a property contains valid binary metadata.
• helpers.getBinaryStream: Mocks the streaming of large files.

Sources: packages/nodes-base/TESTING_PROMPT.md:143-165, packages/nodes-base/utils/tests/binary.test.ts:35-45

Conclusion

Binary Data Management in n8n is characterized by the need for explicit preservation and type-aware extraction. By using preservation patterns like the Merge node "Pass Through" and enabling filesystem storage for high-volume tasks, developers can build resilient workflows that handle complex documents without data loss or memory exhaustion.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/document-processing.ts, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-transformation.ts