N8n Binary And Data Official

n8nOfficialPublished by n8n

Skill
Tool integration
Automation and integrations
Apache-2.0
No issues found

From the author

Use when handling files, images, attachments, or binary data in n8n, OR when an AI agent needs to take a user-uploaded file as tool input or return a generated file. For Data Tables (schemas, dedup, persistent state), see the separate n8n-data-tables-official skill. Triggers on "file", "image", "PDF", "attachment", "binary", "upload", "download", chat trigger with files, agent tool that needs a file, vision/multimodal, or any handling of non-JSON file data.

— the description by n8n

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides the essential patterns for managing binary data (files, images, PDFs) within n8n. Because n8n separates data into JSON and binary slots, and because agent tools are restricted to JSON-only communication, this guide explains how to correctly store, pass, and transform files. It covers the critical 'upload-to-storage-and-pass-key' pattern required to bridge the gap between user-uploaded files and AI agent tools, as well as techniques for maintaining binary context through JSON-heavy workflows.

What it does

Explains the separation of JSON and binary data slots in n8n items.
Provides patterns for reading and writing binary data using Code nodes.
Defines the workaround for passing files into and out of AI agent tools.
Details how to preserve binary data through JSON-only operations using Merge nodes.
Outlines requirements for displaying images in chat surfaces via external storage.
Lists common mime types and best practices for file size management.

When to use it

When your workflow needs to process user-uploaded files or attachments.
When an AI agent needs to perform operations on a file via a tool.
When binary data is being stripped during JSON transformations.
When you need to generate a file in a tool and return it to an agent.
When preparing images for display in chat platforms like Slack or Telegram.

Advantages

Prevents common errors where binary data is lost during workflow execution.
Enables complex AI agent capabilities like vision and document processing.
Optimizes performance by using external storage for large files.
Ensures consistent data handling across different n8n nodes.

Usage examples

“How do I pass an image uploaded in a chat trigger to an AI agent tool?”: You must pre-stage the file by uploading it to private storage, then inject the resulting file key into the agent's system prompt so the tool can download it by key.
“My binary data disappears after an Edit Fields node. How do I fix this?”: Use a Merge node set to 'by position' to combine the output of your JSON transformation with the original stream containing the binary data.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/n8n-io/n8n-binary-and-data-official/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip n8n-binary-and-data-official.zip -d .agents/skills

Documentation by n8n

n8n Binary and Data

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 (chat surfaces, message rendering).

For tabular storage (Data Tables), see the n8n-data-tables-official skill.

Non-negotiables

Binary is in $binary, not $json. Don't read file contents from $json.
Binary cannot cross the agent tool boundary in either direction. Tool parameters are JSON only (via 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.

Strong defaults

Merge nodes keep binary in context. When a side computation strips binary, merge it back rather than re-fetching. See references/MERGE_FOR_CONTEXT.md.

Binary basics

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.

Setting 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',
        },
    },
}]

Reading binary

// 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 tool gymnastics

Agent tools (sub-workflows wired into an AI Agent node or a first-class n8n 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:

Pre-stage uploaded files: hash a key, upload to private storage.
Inject the keys into the agent's system prompt: "Files passed in: [{originalFileName, fileName}]. Use EXACTLY the fileName field when calling tools."
The tool's 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.

Generate binary internally.
Upload to storage, get back URL/key.
Return JSON: { ok: true, file_id: '...', url: '...' }.
The agent embeds the URL in its response, or another tool fetches by key.

For the full pattern including the async-via-webhook variant for long-running tools, see references/AGENT_TOOL_BINARY.md.

Merge for keeping binary in context

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.

CDN requirement for chat surfaces

When a workflow generates an image and the user wants it embedded in a chat message (Slack, Discord, Teams, Telegram, embedded webhook chat, etc.):

Binary on the item isn't enough. Chat surfaces don't read $binary; they render messages that reference images by URL (or via platform-specific file upload APIs).
The image must live somewhere a URL can fetch. Upload to a CDN or object store first.
The user configures this storage. Not built into n8n.

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.

Data Tables

For Data Tables, see the n8n-data-tables-official skill. Distinct surface with its own gotchas (default columns, no foreign keys, no JSON column type, manual-mapping UI quirk).

Reference files

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 a chat surface or other places that need URL-referenced images

Anti-patterns

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 a chat surface to display	Chat surfaces need URL-accessible images (or a platform-native file upload), not raw `$binary`	Upload to CDN, embed URL or use the platform's file API
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

Files

ATTRIBUTION.mdAdded by AutoGineer862 B
LICENSELicence file added by AutoGineer11.0 KiB
SKILL.md7.1 KiB
references/AGENT_TOOL_BINARY.md17.3 KiB
references/BINARY_BASICS.md4.8 KiB
references/CDN_REQUIREMENT.md4.6 KiB
references/MERGE_FOR_CONTEXT.md3.7 KiB

references/CDN_REQUIREMENT.md

CDN requirement for chat-surface images

When a workflow generates an image and the user wants it shown in a chat message (Slack, Discord, Teams, Telegram, embedded webhook chat, etc.):

Image in $binary isn't enough. Chat surfaces don't render raw binary. Either upload to a CDN/object store and embed by URL, or push the bytes via the platform's file-upload API.

The user must provide the storage. n8n doesn't bundle a CDN.

Why

Chat messages render as HTML/JSON. Embedded images reference URLs:

<img src="https://cdn.example.com/img/abc123.png">

Some surfaces (Slack's files.getUploadURLExternal + files.completeUploadExternal two-step, Discord attachments, Telegram sendPhoto) accept binary directly via the platform's file API. Either way, the bytes have to live somewhere the chat client can fetch over HTTPS.

What the user needs

A publicly-accessible URL for the image. Ask the user what they have today, but lead with the recommendation:

Recommended: a real CDN / object storage service. Cloudflare R2 (https://pub-xxxxx.r2.dev/<key>), AWS S3 + CloudFront (https://d1234.cloudfront.net/<key>), Google Cloud Storage, Azure Blob, Backblaze B2, Vercel Blob, Supabase Storage, Bunny CDN. Direct URL embedding works once the bucket or object is public, latency is low because of edge caching, and signed-URL flows are first-class. R2 is the lowest-friction starting point if they don't have anything (~10 minutes, generous free tier, no egress fees).
Drive-style services (fallback): Dropbox, Google Drive, OneDrive, Box. These can produce shareable links, but the URL shape and chat-surface rendering behavior vary, and some require explicitly converting share links to direct-download URLs before they'll embed. Confirm with the user that their service can serve a <img src="...">-renderable URL before committing.
Self-hosted: user serves from their own domain. Fine if it's already there, but don't propose standing one up just for this.

Choice depends on existing infrastructure, costs, and security needs.

What the workflow does

[Generate image] → [Upload to CDN] → [Set: image_url = response URL] → [Send chat reply referencing image_url]

Concretely, with Cloudflare R2:

[OpenAI: generate image]
  ↓ binary on item
[HTTP Request: PUT to R2]
  url: https://<account>.r2.cloudflarestorage.com/<bucket>/<key>
  authentication: AWS-style signed
  bodyContentType: 'binary'
  binaryPropertyName: 'data'
  ↓
[Set: { image_url: 'https://pub-<id>.r2.dev/<key>' }]
  ↓
[Send to chat surface: image_url embedded in the message (markdown, Block Kit image block, adaptive card, etc.)]

Upload mechanics depend on the provider. Most expose S3-compatible APIs usable via n8n's S3 node or HTTP Request with AWS auth.

Telling the user

"I'll generate the image, but the chat surface can't display raw binary. I'll need to upload it somewhere that serves a public URL. What do you use for image / file storage today (R2, S3, GCS, Dropbox, Google Drive, etc.)? If you don't have anything set up, Cloudflare R2 is the lowest-friction starting point (~10 minutes)."

If they don't have storage set up, there's no fallback that hides the requirement: n8n doesn't host the file for them. Pause until they pick a service and provision a bucket / credentials, then resume. Don't quietly ship a workflow that generates images "but they don't display."

Once storage is in place, posting the URL as a link instead of an embedded image is a valid lighter alternative if rendering inline isn't critical, but that still requires the URL to come from somewhere.

URL signing and expiration

Public URL: easy, anyone with the URL can access. Use for non-sensitive content.
Signed URL with expiration: per-request, expires (e.g., 1 hour). Use for sensitive content.

For internal chat surfaces with scoped channels, public is usually fine, since URLs are buried in messages only specific users see. For compliance-sensitive content, default to signed URLs.

File naming

UUIDs: img/abc-123-def-456.png. Random, unguessable. Good default.
Content hash: img/sha256:abc123...png. Free deduplication.
User-prefixed: users/<user_id>/<filename>. Easy per-user cleanup.

Avoid user-controlled filenames (path traversal, collisions) and sequential IDs (predictable, scrapeable).

Cleanup

Configure:

Lifecycle rules: auto-delete after N days (S3, R2, GCS all support).
Cleanup workflow: scheduled, lists and deletes old objects.

7-30 days retention is usually plenty for chat use cases, but ensure you ask the users preference.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

n8n

Publisher

n8n (Official)

Source

n8n-io/skills · skills/n8n-binary-and-data-official · commit 27b6b9f

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by n8n or n8n.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download n8n-binary-and-data-official.zip