GUIDE · Data & Files

n8n Binary Data Explained: Where Files Go and Why They Vanish

2026-10-25 · William Ayad · 10 min read

Two complaints about files in n8n never stop recurring: "the PDF was right there and then it vanished", and "a 20MB attachment crashed the whole instance". Both are one mental model away from solved: every item that flows through n8n has two halves — a json half that nodes read and write with expressions, and a binary half that files live in. The halves travel together but obey different rules: expressions never see the binary half, editors never render it where you expect, and several common nodes silently rebuild items keeping only the json they created. Master which survives what, and the mystery errors stop being mysteries.

The model: binary lives under named keys, not "in" the json

Open any execution's output panel and watch for two tabs: JSON and Binary. Files hang on the Binary side, keyed by name — almost always data (the default everything downstream expects), or whatever name the producing node was told to use. Every file-carrying node declares which binary key to read and which key to write: HTTP Request's "File" response format writes the downloaded bytes into the key you configured; Convert/Extract nodes parse from an input key and emit to an output key; the file-writing nodes read from the key you point them at. The first discipline of binary data is therefore naming discipline: keep one key name end-to-end (stay on data unless something forces otherwise), because half of all "file vanished" reports are nothing but a key renamed midway — the file is present, politely waiting under a name nobody downstream is asking for.

Where the bytes actually live: memory vs filesystem vs S3

The storage mode is an instance-level decision (self-hosted):

Memory mode is why "a few PDFs" can floor an instance: five 20MB attachments is a 100MB execution before any JSON exists (the full RAM story — including why that maps to 503s and "Connection lost" — is in the out-of-memory guide). Filesystem mode is the lightweight fix for most self-hosters — one env line and a path. On n8n Cloud, binary storage is platform-managed; the lever available to you there is smaller per-execution data, not the mode.

Why files vanish: the four-way catalogue

1 · The rebuilder node. Code nodes are the classic: you return { json: {...} } per item and unintentionally construct a brand-new item — the binary half was never copied over, so it is gone from this node onward. Fix: spread or explicitly forward the incoming binary (return { json, binary: item.binary } patterns per item), or set "Include Input Data" where the node offers it.

2 · The renamed key. Producer wrote it to attachment_0; reader still listens to data. Nothing errored; the names just never met. Always open the producer's Binary tab and read the actual key — it is printed there — and align the consumer's "Input Data Field Name" with it.

3 · The merge that married one side. Merge/Combine nodes join json by rule, but binary follows the surviving item: modes that take one input's items wholesale can drop the other input's files without a warning badge. When both sides carry files, verify the Merge node’s Binary tab before blaming anything downstream.

4 · The file never existed here. Disk-reading nodes are deliberately fenced behind an allowlist (N8N_RESTRICT_FILE_ACCESS_TO) — a path outside it fails by design, and in containerized deployments the path often does not exist inside the container at all: the file is on the host, the node reads the container's filesystem. Mount it, or extract the file from the incoming data instead of re-reading disk.

Queue mode adds the geography problem

With queue mode, the node writing the file and the node reading it may execute on different workers. Memory mode breaks outright (worker B cannot see worker A's heap); filesystem mode breaks quietly if each container has its own private disk — one worker's /data/binaryData/xyz.pdf is another worker's file-not-found. The production rule is absolute: queue mode + binary data = a shared filesystem volume across every n8n container, or S3. Diagnosis shortcut: manual runs pass (main process only) while scheduled ones fail (workers) — the same editor-lies split as the credential classes, different victim.

The evidence problem: executions don't keep your files

Expectation meets ledger here: the Executions history persists the json half of items — binary files are not stored in execution history. Debugging "why did yesterday's invoice upload corrupt" therefore requires a habit change: when files matter, make the workflow leave its own evidence — write the incoming file to an archive path early (or ship a copy to an archive branch) as a designed step, so post-mortems inspect artifacts you chose to keep rather than a buffer n8n never promised to retain.

Disk hygiene and backups

Filesystem mode swaps RAM pressure for disk growth: the binary-data directory accumulates with every file-carrying execution and pruning it is on you (mount it on a sized volume, watch it like you watch execution retention). And the backup question changes shape the moment files matter: the disaster-recovery guide backs up workflows, credentials and the encryption key — add the binary-data volume to that set if files are part of your business record, because S3-mode already has its own durability story and a local volume does not.

The five-question flow when a file "disappears"

1. Does the producer's Binary tab show the file? (No → the fetch itself failed; check response format settings or the upstream.)
2. Which key holds it? (Align the consumer's input field name exactly.)
3. Which node first loses the Binary tab? (That's the rebuilder — fix item construction there.)
4. Memory or filesystem mode — and does queue mode share that storage? (Geography question.)
5. Are you reading a host path from inside a container? (Allowlist + mount realities.)

Five questions, ordered by cost. The average "file vanished" thread dies at question two.

The three production shapes that never break

Intake archivism. Webhook receives file → first step writes a pristine copy to the archive location → only then does processing begin. Whatever happens downstream — rebuilder nodes, retries, worker crashes — the evidence and the re-runnable input exist. This is the shape for invoices, contracts, anything you'd have to apologize for losing.

Single-key fetch-convert-forward. HTTP Request (response format: File) writes data → Convert to File / Extract from File reads data, writes data → forwarder uploads data. One key end-to-end, zero rename hunts; the chain can grow nodes without growing mystery. Rename only with a reason, and only at known joints.

Fleet mode. Queue mode, binary mode s3, archive targets on durable storage, and per-execution sizes kept honest by the intake allowlist patterns — the shape that lets workers come and go without file geography ever entering the incident channel. Each of the three is just today's knuckles from this guide, pre-assembled into a pipeline that does not surprise.

Telling apart "file problem" from "platform problem"

When the symptom text is ambiguous — ENOENT, file-not-found, read-after-crash chains, 503s that smell like memory — classify before rearchitecting: the free Error Doctor pattern-matches documented crash classes (storage and connection classes included) from the pasted error text in about two seconds, in your browser. And when the file pipeline itself is still on the drawing board, the free audit preflights the structural layer around it — webhook hardening at the intake, retry coverage on the storage call — on the exported JSON, free and local. Honest boundary, as always: static export analysis cannot weigh your files' sizes or your disk's mood; mode and volume sizing remain the operator's measurement, guided by the sections above.

The pre-built layer, if you want it

The n8n Reliability Kit (one-time $19 — disclosing: mine) bundles this discipline where teams actually lose it: the documented failure library carries the binary-vanish and storage-mismatch classes with incidence context and prevention steps; the 34-point preflight checklist makes binary hygiene (consistent keys, rebuild-node checks, shared-storage rule) a launch-day ritual rather than tribal knowledge; the decision trees walk "file missing / worker cannot read / memory explodes" to their distinct fixes; and the production blueprints include file-pipeline skeletons with archive-and-forward evidence steps pre-wired. Browser-local like everything else we ship: your files and exports never leave the machine.

Frequently asked questions

Where did my file go after the previous node?

Check that node's Binary tab — no tab means the file never survived it, and a rebuilder (Code-node item construction, a one-sided Merge) almost always did it. Forward the binary half explicitly or align the key names; the file is rarely destroyed, usually orphaned.

Does binary data use RAM?

In default mode, yes — files live in process memory for the execution's whole life, multiplicatively across attachments. N8N_DEFAULT_BINARY_DATA_MODE=filesystem moves bytes to disk and items to references; S3 does the same at fleet scale — and queue mode makes shared storage effectively mandatory.

Why does it work manually but fail in queue mode?

Manual runs live on the main process; real runs live on workers. Files written to one container's private disk are invisible to the others — share the volume across all n8n containers or move binary storage to S3.

Does switching binary mode need a restart — and do files survive?

Yes to the restart: the env var applies at process boot. No data is deleted — memory-mode files simply were never on disk. Re-run one file-heavy workflow afterward, confirm items land in the binary-data directory, and only then treat queue-mode cutovers as safe.

Can I inspect a file from an old execution?

No — history keeps json, not binaries. Design the evidence instead: archive steps for business-critical files, so a post-mortem reads artifacts you chose to keep.

The one-paragraph answer to bookmark

files in n8n are passengers under named keys on the binary half of each item: they vanish when a node rebuilds items and leaves them behind, when producer and consumer ask for different key names, when a merge keeps one side, or when the path lived on a host your container cannot see — and they explode memory when default mode meets big attachments. Keep one key name end-to-end, choose filesystem or S3 by fleet shape, share storage explicitly in queue mode, and archive early whatever you would grieve losing — the rest is five questions asked in the right order.