Binary files in n8n look simple until they are not.

A workflow works during the first test, then fails later with “file not found.” A webhook receives a file, but the next node cannot see it. A pinned execution looks correct, but rerunning it breaks. These issues are common because binary data behaves differently from normal JSON.

Here are the mistakes I see most often.

1. Assuming pinned binary data keeps the actual file forever

Pin Data is useful, but it can be misleading for binary workflows. The pinned execution may keep a reference to the binary file, not a permanent copy of the file itself.

On self-hosted n8n, the file may still exist on local disk. On n8n Cloud, temporary binary storage can expire. That means the pinned data still looks present, but the actual file behind it is gone.

If the workflow depends on a file, resend the real webhook request during debugging or store the file in durable storage first.

2. Using the wrong binary property name

Many n8n nodes expect a specific binary property name, often something like data, file, or attachment.

If one node outputs binary.file but the next node expects binary.data, the workflow can fail even though the file is technically present.

Before debugging the whole workflow, inspect the execution data and confirm the exact binary key.

3. Sending the wrong content type to a webhook

For file uploads, the request usually needs multipart/form-data. If the request sends application/octet-stream or raw body data, the webhook may parse the file differently than expected.

This is especially important when another system sends the file to n8n automatically. A browser form, API client, and backend service can all send the same file in different ways.

4. Not saving important files before processing

If the file matters, store it early. Upload it to Google Drive, S3, R2, a database-backed file store, or another durable location before doing complex transformations.

This gives you a stable reference for retries. It also makes the workflow easier to audit because you can answer: which file was processed, when, and from where?

5. Mixing metadata and binary data

File workflows usually need both:

  • Metadata: file name, MIME type, source, user ID, client ID, date, status.
  • Binary data: the actual file bytes.

If you only pass the file and forget the metadata, later steps become fragile. If you only keep metadata and lose the file reference, retrying becomes difficult.

6. Forgetting file size and timeout limits

Large files can hit node limits, API limits, memory pressure, or timeouts. This is common with PDFs, images, videos, and bulk uploads.

For larger workflows, add guardrails:

  • Check file size before processing.
  • Reject unsupported MIME types early.
  • Store files before long processing steps.
  • Send a clear failure message to the operator.

Final takeaway

Binary data is not just another JSON field. Treat it like a temporary file that needs careful naming, storage, validation, and retry handling.

If your n8n workflow processes files, design the file path first. Then build the workflow around that path.

If you want help debugging or rebuilding a file-heavy n8n workflow, send me the workflow context. I can help identify where the binary reference is getting lost.