n8n-binary-and-data-official

name

n8n-binary-and-data-official

description

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.

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

1. Binary is in $binary, not $json. Don't read file contents from $json.
2. 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: { ... },           
    : {                
        : {              
            : ,
            : ,
            : ,
            : ,
        },
    },
}