n8n Binary Data: Working With Files, Images and PDFs (and Why They Disappear)
By Abhishek Patoliya · 2026-08-16
Files in n8n (a PDF from an email, an image from a form upload, a CSV from an API) don't live in $json. They travel in a separate binary part of each item, and most "my file disappeared" problems come from not knowing that. This lesson covers where binary data lives, the nodes that convert it, reading it in a Code node, sending files to APIs, and the memory setting that matters for large files on self-hosted n8n.
Before you start: read the Code node. Facts below follow n8n's binary-data and data-structure documentation as of 9 November 2026.
Where a file lives on an item
Every item has a json part and may have a binary part. binary is an object keyed by property name, and each file inside it carries the data plus metadata:
{
json: { invoiceId: "INV-1042" },
binary: {
data: { // the property name; many nodes default to "data"
data: "...", // the file content (managed by n8n)
mimeType: "application/pdf",
fileName: "INV-1042.pdf",
fileExtension: "pdf"
}
}
}
One item can carry several files under different names (original, thumbnail), and nodes that read files ask for the binary property name. A node looking for data won't find a file stored under attachment_0, which is the usual cause of "no binary data found". The node's output panel has a Binary tab showing each property's name, type and size.
In an expression, the current item's file metadata is at {{ $input.item.binary.data.mimeType }} and {{ $input.item.binary.data.fileName }} (replace data with your property name).
Nodes that work with files
| Node | Use it to |
| Extract From File | Turn a file into JSON: CSV/XLSX rows, PDF text, JSON files, or the file as a base64 string in a field |
| Convert to File | Turn JSON into a file: CSV, XLSX, JSON, HTML, ICS, or a base64 string back into a binary file (Move Base64 String to File) |
| Read/Write Files from Disk | Read or write files on the machine running n8n (self-hosted) |
| Compression, Edit Image | Zip/unzip; resize, crop or annotate images |
| HTTP Request | Download a file (Response Format: File) or upload one (body type n8n Binary File or Form-Data) |
Reach for these before writing code. Converting a file to base64 for an API that wants it in JSON is Extract From File → Move File to Base64 String, with no Code node needed.
Why files disappear
- A Code node returning new items without
binary. If you build items as { json: {...} }, the file isn't copied. Carry it explicitly: { json: {...}, binary: item.binary }.
- Edit Fields has an Include Binary Data option; check it if files vanish after reshaping (see Edit Fields).
- Aggregate only carries files with its Include Binaries option on (see Aggregate).
- Wrong property name downstream (see above).
To find the step that lost it, open each node's output from the trigger forward and check the Binary tab.
Reading file bytes in a Code node
Use the documented helper. n8n's docs say to always use it rather than older methods such as reading items[0].binary.data.data directly, because n8n may store the bytes outside the item:
// Run Once for All Items: size of each PDF in KB
const items = $input.all();
for (let i = 0; i < items.length; i++) {
const buffer = await this.helpers.getBinaryDataBuffer(i, 'data'); // (itemIndex, propertyName)
items[i].json.sizeKb = Math.round(buffer.length / 1024);
}
return items; // the same items, so their binary data is kept
getBinaryDataBuffer() isn't available in Python Code nodes.
Sending a file to an API
- Multipart upload (most file-upload endpoints): HTTP Request with body type Form-Data, adding a field of type n8n Binary File with your property name.
- Raw body: body type n8n Binary File.
- Base64 inside JSON (many vision-model APIs): Extract From File → Move File to Base64 String, then reference that field in the JSON body. Check the API's size limit first, because base64 adds about a third to the size. See invoice extraction with vision models.
Routing by file type and size
Check the type early and route with a Switch node with a fallback output, so an unexpected type gets a clear message rather than failing three nodes later:
{{ $input.item.binary.data.mimeType.startsWith('image/') }} → image branch
{{ $input.item.binary.data.mimeType === 'application/pdf' }} → PDF branch
fallback → "Unsupported file type" reply
Reject oversized files at intake, too. The Binary tab shows the size, and the Code example above shows how to measure it.
Large files on self-hosted n8n: the binary data mode
By default n8n keeps binary data in memory (N8N_DEFAULT_BINARY_DATA_MODE=default), and its docs warn this can crash an instance working with large files. Options:
filesystem: store files on disk (path set by N8N_BINARY_DATA_STORAGE_PATH).
database: store in the database. This is what n8n recommends for queue mode, which doesn't support filesystem. The per-file limit (N8N_BINARY_DATA_DATABASE_MAX_FILE_SIZE) defaults to 512 MiB.
s3 / azure: external storage on self-hosted Business and Enterprise plans.
Even with disk storage, avoid carrying very large files through many nodes. Upload to object storage early and pass a URL, and fetch the bytes only in the step that needs them. Self-hosting setup is covered in self-hosting n8n.
Key takeaways
- Files live in
item.binary.<propertyName> with mimeType, fileName and fileExtension, not in $json.
- Use Extract From File / Convert to File / HTTP Request options before writing code.
- In a Code node, carry
binary forward and read bytes with getBinaryDataBuffer().
- Most "missing file" errors are a dropped
binary or the wrong property name.
- Self-hosted with large files: switch the binary data mode away from in-memory (database for queue mode).
Exercise: download a public PDF with an HTTP Request node (Response Format: File). Add the Code node above to compute its size, then Extract From File to get its text, and check where the binary is still present at each step. Next lesson: the HTTP Request node.
References (checked 9 November 2026)
Written by Abhishek Patoliya, Senior n8n Developer & Automation Architect, Surat, India. Verified n8n Creator.