n8n Code Node Binary Data: Read, Change and Return Files

Files in n8n (PDFs, images, CSV exports, audio) travel as binary data next to the usual JSON. The Code node can read and change them, but only through the right helper. Old forum snippets that read items[0].binary.data.data directly break on current versions, because n8n may store the file outside the item. Here is the method the documentation recommends, and the patterns built on it.

How binary data looks in an item

An item that carries a file has two parts: json for regular fields and binary for files, keyed by a property name. Most nodes use data as the default name.

{
  json: { orderId: 812 },
  binary: {
    data: {
      fileName: 'invoice-812.pdf',
      mimeType: 'application/pdf',
      fileExtension: 'pdf',
      // the content itself, or a reference to where n8n stores it
    },
  },
}

Depending on your configuration, n8n keeps file contents in memory or on disk, so never assume the content sits in the item. That is why the helper exists.

Read the file content

The documented method returns the content as a Buffer for any item and binary property:

// Mode: Run Once for All Items
const buffer = await this.helpers.getBinaryDataBuffer(0, 'data');
const text = buffer.toString('utf8');
return [{ json: { length: buffer.length, preview: text.slice(0, 200) } }];

The first argument is the item index, the second the binary property name. The documentation is explicit that you should always use this function and avoid the older items[0].binary.data.data approach.

Example: add a header row to a CSV

const out = [];
const items = $input.all();
for (let i = 0; i < items.length; i++) {
  const buffer = await this.helpers.getBinaryDataBuffer(i, 'data');
  const csv = 'email,company,source\n' + buffer.toString('utf8');
  out.push({
    json: items[i].json,
    binary: {
      data: {
        data: Buffer.from(csv, 'utf8').toString('base64'),
        mimeType: 'text/csv',
        fileName: items[i].binary.data.fileName || 'export.csv',
      },
    },
  });
}
return out;

Returning binary content as a base64 string in data, with mimeType and fileName, is the standard item format that the next nodes read.

Example: hash a file

Useful to detect duplicates or prove a document did not change. crypto is available in the Code node, on Cloud as well.

const crypto = require('crypto');
const out = [];
const items = $input.all();
for (let i = 0; i < items.length; i++) {
  const buffer = await this.helpers.getBinaryDataBuffer(i, 'data');
  const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
  out.push({ json: { ...items[i].json, sha256 }, binary: items[i].binary });
}
return out;

Keep binary: items[i].binary in the output if later nodes still need the file. A Code node only passes on what it returns.

Example: rename a file before uploading it

The HTTP Request node uses the binary file name, not the form field name, when it sends multipart data. The documentation gives this exact fix:

for (const item of $input.all()) {
  item.binary.data.fileName = 'index.html';
}
return $input.all();

Set item.binary.data.mimeType too if the receiving API checks the content type.

When to skip the Code node

Use code for what those nodes cannot do: custom parsing, merging files, checks and hashes.

Limits to know

• getBinaryDataBuffer() is not supported in Python.
• Large files use memory when you load the whole buffer. Process big exports in batches or let dedicated nodes stream them.
• On n8n Cloud there is no file system access from the Code node. Use the file nodes instead.

Worked example: merge several CSV exports into one file

Your accounting tool exports one CSV per store, and you want one combined file for the weekly report. Each item from the previous node carries one CSV in binary.data.

const items = $input.all();
let header = null;
const rows = [];
for (let i = 0; i < items.length; i++) {
  const buf = await this.helpers.getBinaryDataBuffer(i, 'data');
  const lines = buf.toString('utf8').split(/\r?\n/).filter(Boolean);
  if (!lines.length) continue;
  if (!header) header = lines[0];
  rows.push(...lines.slice(1));
}
const csv = [header, ...rows].join('\n');
return [{
  json: { files: items.length, rows: rows.length },
  binary: { data: {
    data: Buffer.from(csv, 'utf8').toString('base64'),
    mimeType: 'text/csv',
    fileName: `weekly-${$now.toFormat('yyyy-LL-dd')}.csv`,
  } },
}];

The output is one item with a summary in json and the merged file in binary. Send it with an email node or upload it to storage. This approach assumes all exports share the same header; check that before combining files from different sources.

How n8n stores binary data

n8n can keep file contents in memory or write them to disk (and, on some setups, external storage), depending on the instance configuration. In memory mode the content may sit in the item; in filesystem mode the item only holds a reference. Code that reads item.binary.data.data directly therefore works on one instance and fails on another. getBinaryDataBuffer() hides that difference, which is why the documentation insists on it.

Binary data also counts toward execution data. Large files kept on many items make executions heavy to store and to open in the editor. Drop files you no longer need by returning items without binary once a file has been uploaded.

Text, base64 and encodings

Troubleshooting table

Common mistakes to avoid

• Assuming data is always the property name. Some nodes let users rename it.
• Holding hundreds of files in one execution. Loop in batches and upload as you go.
• Base64 files inside JSON bodies when the API accepts multipart. Base64 adds about a third to the size; multipart is lighter.

Production checklist

• Binary read with getBinaryDataBuffer(), never from the item directly.
• binary passed on in the output when later nodes need the file.
• File name and MIME type set explicitly before uploads.
• Large files processed in batches to keep memory stable.

Frequently asked questions

How do I get the binary data in an n8n Code node?

Use await this.helpers.getBinaryDataBuffer(itemIndex, 'propertyName'). It returns a Buffer you can read with .toString() or pass to crypto.

Why is item.binary.data.data empty or wrong?

n8n may store binary content outside the item, depending on the binary data mode. Reading the property directly is not reliable. Use getBinaryDataBuffer().

How do I return a file from a Code node?

Return an item with a binary object: a property (usually data) containing base64 data, a mimeType and a fileName. For simple text or JSON files, the Convert to File node does it without code.

Can I use binary data in a Python Code node?

getBinaryDataBuffer() is not available in Python. Handle files with the dedicated nodes, or use JavaScript for that step.

How do I convert a binary file to text in the n8n Code node?

Read it with await this.helpers.getBinaryDataBuffer(index, 'data'), then call .toString('utf8') on the Buffer.

How do I create a PDF or image in the Code node?

The Code node is not a renderer. Generate files with a dedicated service or node (for example an HTML to PDF API through the HTTP Request node), then handle the result as binary.

How large can files be in n8n?

It depends on memory and the binary data mode of your instance. Webhooks accept 16 MB by default (N8N_PAYLOAD_SIZE_MAX on self-hosted).

Steve, founder of PURIST

Steve founded PURIST, a workflow automation studio working with n8n, Make and Claude AI, and is the point of contact on every project. Prices and features in our articles come from vendor documentation and public pricing pages. How we research and score tools.