Handle files and binary data in n8n workflows

This skill governs how n8n workflows handle files and binary data - reading, transforming, storing, uploading, downloading, or transmitting files and binary fields, including multimodal agent inputs and chat attachments. It treats uploaded files and generated URLs as potentially sensitive: get approval before sending data to a new external host, use the narrowest retention/access scope available, avoid logging bytes or base64 payloads, and never embed credentials in URLs or workflow fields.

Its foundation is that every n8n item carries two independent, side-by-side slots: $json for structured data and $binary for file bytes - file contents (a PDF, image, zip) live only in $binary, never in $json. Three rules prevent most binary bugs: file contents are in $binary, not $json (reading $json.data for file contents returns nothing); binary cannot cross the AI-agent tool boundary in either direction, since tool arguments and returns are JSON-only, so files must be pre-staged to storage and passed as a key or URL; and chat surfaces (Slack, Discord, Teams, Telegram, embedded webhook chat) render images by URL, never by reading $binary, so the file must live somewhere a URL can fetch it.

Each item's binary slot is keyed by a binary property name (default data) pointing to an object with base64 data, mimeType, fileName, and fileExtension; $json and $binary are separate namespaces that never mix, and a webhook receiving multipart/form-data puts the file in $binary and the accompanying fields in $json.body. Binary is usually produced by nodes rather than hand-built: HTTP Request with responseFormat: "file", Read/Write Files from Disk, storage downloads (S3, Google Drive, Dropbox, etc.), email-attachment triggers, or AI media-generation nodes via options.binaryPropertyOutput - leaving responseFormat at its JSON/string default is the classic reason a download ends up as garbled text instead of clean bytes. In a Code node, read raw bytes with the getBinaryDataBuffer helper (never hand-decode base64) and re-attach binary: $input.item.binary on return, since a Code node returning [{ json: {...} }] without it silently drops the file; write binary by building the slot with base64 data, mimeType, fileName, and fileExtension.

JSON-only nodes (Edit Fields/Set, Code, IF, etc.) can silently strip the $binary slot from their output with no validation error - fixed either by a pass-through option on the transforming node (Edit Fields' includeOtherFields, or a Code node explicitly returning the binary) or by fanning the source into both the transform and a bypass branch, then recombining with a Merge node in combineByPosition mode. The agent-tool binary boundary is the sharpest edge: for inbound files, split a chat trigger's files[] array, upload each to private storage under a hashed key, re-merge as a synchronization barrier before the agent runs with executeOnce: true, and inject both the human-readable name and the storage key into the agent's system prompt so the tool can fetch by key; for outbound files, a tool sub-workflow generates the binary, uploads it, and returns JSON like {ok, key, url, mimeType} for the agent to embed. passthroughBinaryImages: true only changes what the LLM sees for vision - it does not let tools receive files, and covers images only.

For chat surfaces, since clients render by URL rather than reading $binary and n8n ships no built-in CDN, the bytes must be uploaded to user-provided storage (object stores like S3/R2/GCS/Azure Blob/Backblaze B2/Supabase Storage, or drive-style services like Dropbox/Google Drive/OneDrive/Box, with Cloudflare R2 as the lowest-friction default) and a signed, expiring URL used for sensitive content. Explicitly unavailable: $fromAI() cannot carry binary (only strings/numbers/booleans/objects), tool arguments/returns have no binary parameter, n8n has no CDN or public file host, and getBinaryDataBuffer is a Code-node helper unavailable in the Custom Code Tool sandbox. Persistent tabular storage (reference-counting staged files, dedup) belongs to the separate n8n_manage_datatable surface, not this skill.

Nine documented anti-patterns cover reading file contents from $json, skipping responseFormat: "file" on HTTP downloads, a Code node dropping binary on return, a JSON transform eating binary, passing an uploaded file through $fromAI, misreading passthroughBinaryImages as a tool channel, a tool returning raw binary instead of a JSON key/URL, posting $binary directly to a chat surface, and hardcoding base64 in a Code node. Since a stripped binary slot is a silent failure invisible to validation, verification requires running n8n_test_workflow or a real trigger, then inspecting the execution via n8n_executions per-node to confirm the binary slot's presence and metadata at the node just before it disappears.

Use whenever an n8n workflow reads, transforms, stores, uploads, downloads, or transmits files and binary fields, including multimodal agent inputs and chat attachments. It does not cover Data Tables (owned by n8n-mcp-tools-expert), Code-node sandbox/execution-mode detail (owned by n8n-code-javascript/n8n-code-python), or the Custom Code Tool contract itself (owned by n8n-code-tool).

Input is an n8n item carrying $json and $binary slots, or a file arriving via HTTP download, disk read, storage download, email attachment, or AI media generation. Output is correctly preserved binary data through transforms, agent-tool boundaries, and chat-surface delivery - either passed through directly or staged to storage and referenced by key/URL.

// Code node, "Run Once for Each Item"
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); // (itemIndex, propertyName)
const text = buffer.toString('utf-8');
const length = buffer.length;

return [{
  json: { ...$json, length },
  binary: $input.item.binary,   // pass the binary through, or it's gone
}];

n8n-code-javascript/n8n-code-python (Code-node sandbox and helpers), n8n-code-tool (Custom Code Tool's narrower sandbox with no $binary/getBinaryDataBuffer/$fromAI), n8n-workflow-patterns (the AI-Agent-with-tools shape), n8n-node-configuration (conditional fields like responseFormat, binaryPropertyName), n8n-expression-syntax ($binary.<key> vs $json.body addressing), n8n-validation-expert (validation can't catch a dropped binary slot), n8n-mcp-tools-expert (Data Tables and n8n_executions), n8n-error-handling (error branches for storage uploads/downloads), and using-n8n-mcp-skills as the overall skill index.

n8n workflow builders handling files - PDFs, images, attachments, AI-generated media - who need to keep binary data intact across JSON transforms, AI-agent tool calls, and chat-surface delivery instead of losing it to a silent strip.