Help us improve
Share bugs, ideas, or general feedback.
From n8n-skills
Handles files, images, attachments, and binary data in n8n workflows. Covers agent tool binary constraints, merge context, and Code node read/write patterns.
npx claudepluginhub n8n-io/skills --plugin n8n-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/n8n-skills:n8n-binary-and-dataThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
n8n handles two kinds of data: JSON (in `$json`) and binary (in `$binary`), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (e.g., chat hub).
Guides when to use n8n's Agent node vs Basic LLM Chain, Text Classifier, or media generation nodes for AI features like agents, RAG, and structured output.
Builds, tests, and deploys n8n workflows via REST API with incremental node testing. Activates for automation creation, workflow debugging, nodes, expressions, credentials, and JS/Python Code nodes.
Creates, edits n8n workflows as TypeScript files with node docs access and n8nac CLI for workspace init, preventing param errors.
Share bugs, ideas, or general feedback.
n8n handles two kinds of data: JSON (in $json) and binary (in $binary), flowing side-by-side. Binary has sharp edges around agent tools, storage, and display contexts (e.g., chat hub).
For tabular storage (Data Tables), see the n8n-data-tables skill.
$binary, not $json. Don't read file contents from $json.fromAi()), and tool results are JSON only. Pre-stage binary in storage and pass keys/URLs through JSON. The agent's passthroughBinaryImages: true lets the LLM see uploaded images for vision, but it does NOT enable tools to receive them. See references/AGENT_TOOL_BINARY.md.references/MERGE_FOR_CONTEXT.md.In n8n, each item has two slots:
{
json: { ... }, // your data
binary: { // your files
data: { // 'data' is the typical key; can be any name
data: '<base64>',
mimeType: 'application/pdf',
fileName: 'invoice.pdf',
fileExtension: 'pdf',
},
},
}
$binary.<key> reads the named property. Most file-handling nodes have a binaryPropertyName parameter, the key inside $binary.
File-producing nodes (HTTP Request with binary response, Read Files, etc.) populate $binary automatically. To produce binary in a Code node:
return [{
json: { ... },
binary: {
data: {
data: Buffer.from(content).toString('base64'),
mimeType: 'text/plain',
fileName: 'output.txt',
},
},
}]
// In a Code node
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data')
const text = buffer.toString('utf-8')
Most workflows don't need to read binary directly. Pass it through to consumer nodes (email attachments, file uploads, etc.).
See references/BINARY_BASICS.md for more.
Agent tools (sub-workflows wired into a LangChain Agent, or workflows exposed as MCP tools) have a constraint: parameters and results are JSON, not binary. Affects both directions.
Inbound (user uploads → tool consumes): the chat trigger gives files[]. The agent can have passthroughBinaryImages: true for vision, but fromAi() can't pass binary to a tool. So:
fileName field when calling tools."fromAi('imageName', '...', 'string') receives the key. The sub-workflow downloads from storage.Outbound (tool produces → agent returns): a tool generates a file. It can't return raw binary.
{ ok: true, file_id: '...', url: '...' }.For the full pattern including the async-via-webhook variant for long-running tools, see references/AGENT_TOOL_BINARY.md.
A JSON-only operation (Edit Fields, Code, IF) often strips binary from the item. To keep it:
[Source with binary] ─┬─→ [Edit Fields: transform JSON] ─┐
│ ├─→ [Merge: by position] ─→ [Email with attachment]
└─────────────────────────────────────┘
Merge combines the streams, and binary survives. See references/MERGE_FOR_CONTEXT.md.
When a workflow generates an image and the user wants it in the chat UI:
$binary.Common options span object storage (S3, R2, GCS, Azure Blob, Vercel Blob, Supabase Storage) and drive-style services (Dropbox, Google Drive, OneDrive, Box). Ask the user what they use rather than defaulting to S3.
See references/CDN_REQUIREMENT.md.
For Data Tables, see the n8n-data-tables skill. Distinct surface with its own gotchas (default columns, no foreign keys, no JSON column type, manual-mapping UI quirk).
| File | Read when |
|---|---|
references/BINARY_BASICS.md | First time handling binary, or reading/writing the $binary slot |
references/AGENT_TOOL_BINARY.md | Agent tool needs a user-uploaded file, or produces a file (the boundary in either direction) |
references/MERGE_FOR_CONTEXT.md | Binary disappears after a JSON transform and needs to re-attach |
references/CDN_REQUIREMENT.md | Showing images in chat hub or other places that need URL-referenced images |
| Anti-pattern | What goes wrong | Fix |
|---|---|---|
Trying to read file content from $json | Binary isn't in $json | Use $binary |
| Building an agent tool that returns binary directly | Tool output is JSON-only, so binary doesn't survive | Upload to storage, return key/URL in JSON (see AGENT_TOOL_BINARY.md) |
Trying to pass uploaded chat files into a tool via fromAi | fromAi doesn't carry binary, so the tool gets nothing | Pre-stage uploads to storage, inject keys in the system prompt, and have the tool download by key |
Setting passthroughBinaryImages: true and assuming tools can now see the file | The flag only affects what the LLM sees, not what tools receive | Still need the upload-and-pass-key pattern for tools |
| Losing binary after a JSON transform | The transform's output item doesn't have binary | Use Merge to combine the JSON output with the binary stream |
| Storing image in n8n binary and expecting chat hub to display | Chat hub needs URL-accessible images, not raw binary | Upload to CDN, embed URL in response |
| Hardcoding binary base64 in a Code node | Massive workflow JSON, slow, leaky | Reference binary via $binary properly, or upload to storage and reference by URL |