<!-- BusyBot node reference — https://busybot.net/tools/write-binary-file/ -->

> Node: Write Binary File (`write_binary_file`) · Action (binary) · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Write Binary File

> Write binary data to a file on disk

## Overview

The Write Binary File tool reads binary data from an input item's binary property and writes it to a specified file path within the execution files directory. Supports both overwrite and append modes. This is the legacy single-file writer — the modern replacement is the read_write_file tool. All write operations are sandboxed to the execution-scoped directory to prevent directory traversal attacks. The tool preserves all original JSON data and binary properties on the output, adding the written file path as a confirmation field.

**Category:** Core Nodes  
**Tool Name:** `write_binary_file`  
**Version:** 1

**Appearance:** Icon: `lucide-FileUp` | Color: `#6b7280`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| File Name | `string` | Yes | — | Path to which the file should be written, relative to the execution files directory. Include the file extension. Supports expressions like {{ $json.fileName }}. |
| Property Name | `string` | Yes | `data` | Name of the binary property on the input item which contains the data to write to the file. |
| Options | `collection` | No | `{}` | Extra write settings. |
| — Append | `boolean` | No | `false` | Whether to append to an existing file instead of overwriting it. If the file does not exist, it is created. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The input item JSON passes through unchanged, with one field added:

- `fileName` — the path you asked to write, exactly as you supplied it (relative, including any subdirectories).

The written file is also attached back to the item as binary data under the same name as **Property Name**, with its `fileName`, `mimeType` and `fileSize` in bytes, merged with any binary the item already carried. Binary properties other than the one you wrote are untouched.

Reference the write downstream by expression, e.g. `{{ $json.fileName }}`.

## Usage Examples

- Write a downloaded PDF to a file on disk
- Save an image attachment to the filesystem
- Append log data to a text file
- Export a generated report to a file

## Example Configuration

Write the item's `data` binary to a file:

```json
{
  "type": "write_binary_file",
  "parameters": {
    "fileName": "output.bin",
    "dataPropertyName": "data",
    "maxConcurrency": 5
  }
}
```

Append to an existing file:

```json
{
  "type": "write_binary_file",
  "parameters": {
    "fileName": "logs/system.log",
    "dataPropertyName": "logData",
    "maxConcurrency": 1,
    "options": {
      "append": true
    }
  }
}
```

Write a named binary property into a subdirectory:

```json
{
  "type": "write_binary_file",
  "parameters": {
    "fileName": "files/document.pdf",
    "dataPropertyName": "pdfContent",
    "maxConcurrency": 3,
    "options": {
      "append": false
    }
  }
}
```

Give each item its own file:

```json
{
  "type": "write_binary_file",
  "parameters": {
    "fileName": "uploads/{{ $json.id }}.jpg",
    "dataPropertyName": "imageData",
    "maxConcurrency": 5
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Write binary data from an input item to a file in the execution files directory (deprecated — use read_write_file instead).

### Behavior notes

- **Prefer Read/Write Files from Disk.** This node is kept for existing workflows; the newer node writes the same way and reads as well.
- **The item must actually carry the binary property.** If the property named by Property Name is missing, the item fails — check the upstream node's Binary Data panel for the exact, case-sensitive name.
- **Subdirectories are created for you.** `reports/2026/summary.pdf` works without a separate step; the parent folders are made if they do not exist.
- **Paths are relative and sandboxed.** Every write is resolved inside this execution's own files directory. An absolute path, or one that climbs out with `..`, is rejected.
- **Give every item a distinct path when writing in parallel.** With a fixed File Name and several items, each write overwrites the last — put an expression such as `{{ $json.id }}` in the path, or set Append and Max Concurrency to 1 when you really want one accumulating file.
- **Files live for the run.** The execution files directory is scoped to the execution, so a later step in the same workflow can read the file back — but to keep it, upload it or attach it as binary before the run ends.