n8n-binary-and-data

n8n Binary and Data

When to Use

Use this skill when an n8n workflow reads, transforms, stores, uploads, downloads, or transmits files and binary fields, including multimodal agent inputs and chat attachments.

Treat uploaded files and generated URLs as potentially sensitive. Obtain approval before sending data to a new external host, use the narrowest retention and access scope available, avoid logging bytes or base64 payloads, and do not embed credentials in URLs or workflow fields.

Every n8n item carries two independent slots: $json for structured data and $binary for file bytes. They travel side by side through the workflow. File contents — the actual PDF, image, or zip — live in $binary, never in $json. Get that split wrong and you read an empty field, lose a file mid-flow, or hand an AI agent a tool input it can't use.

This skill covers where binary lives, how to read and write it, how to keep it from being silently stripped, the hard wall between binary and the AI-agent tool boundary, and why chat surfaces need a URL instead of raw bytes.

---

The three rules that prevent 90% of binary bugs

1. File contents are in $binary, not $json. After an HTTP download, a "Read Files", or an email-attachment trigger, the bytes sit in $binary.<key>. $json holds metadata at most. Reading $json.data for file contents gives you nothing.

1. **Binary ca