n8n Excel Node File Corrupted Error

 

Who this is for: Workflow developers using n8n who need to read or write Excel files reliably, especially in Docker or Kubernetes deployments. We cover this in detail in the n8n Node Specific Errors Guide.

---

Quick Diagnosis

Step	Action
1	Ensure the upstream node outputs binary data with the correct data property (e.g., data: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet").
2	Insert a Set node before the Excel node → binary.property = "data" and enable “Keep Only Set”.
3	In the Excel node, toggle “Read from Binary” (or “Write to Binary” for output) and point to the same property name.
4	If the source file is a CSV, convert it to XLSX first with a Spreadsheet → Convert CSV to XLSX node or a tiny JavaScript function.
5	Verify file‑system permissions on the execution environment – the process must be able to read/write the temporary folder (/tmp by default).

Apply these steps and re‑run the workflow; the error disappears.

---

1. What the “File corrupted” error really means

If you encounter any n8n smtp node send failure resolve them before continuing with the setup.

The Excel node uses the exceljs library. When it receives a binary payload that cannot be parsed, it throws:

Error: File is corrupted or not a valid Excel workbook

Typical triggers:

• Empty or truncated binary data.
• MIME type that does not match the content (e.g., text/plain instead of the XLSX MIME).
• Read‑only mount or missing write permission for the temporary folder used by exceljs.

EEFA note: In production containers, /tmp may be mounted with noexec. ExcelJS writes a temp file before parsing; a noexec mount causes the same “corrupted” message.

---

2. Common causes in n8n workflows

If you encounter any n8n mysql node connection timeout resolve them before continuing with the setup.

Cause	Symptom	How to spot it
Binary property mismatch	“File corrupted” right after an HTTP Request node that returns a file	Inspect the binary object in the node’s output (debug panel).
Incorrect MIME type	Error even though the file opens locally	Look at binary.property.mimeType.
Large files (>50 MB)	Intermittent failures, sometimes “Out of memory” followed by “File corrupted”	Check the size field in the binary metadata.
Permission issues	Works locally, fails on self‑hosted server	SSH in, run ls -l /tmp – ensure the n8n user can write.
CSV passed to Excel node	“File corrupted” despite tabular data	Verify the source node’s format; CSV must be converted first.

---

3. Step‑by‑step troubleshooting workflow

Below is a ready‑to‑import JSON that builds a minimal debugging chain for the Excel node.

3.1 Fetch the workbook (HTTP Request)

{
  "name": "HTTP Get XLSX",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 2,
  "parameters": {
    "url": "https://example.com/report.xlsx",
    "responseFormat": "file"
  },
  "position": [200, 300]
},

3.2 Normalise the binary property

{
  "name": "Set Binary Property",
  "type": "n8n-nodes-base.set",
  "typeVersion": 2,
  "parameters": { "binaryPropertyName": "data" },
  "keepOnlySet": true,
  "position": [500, 300]
},

3.3 Read the workbook with the Excel node

{
  "name": "Excel Read",
  "type": "n8n-nodes-base.excel",
  "typeVersion": 2,
  "parameters": {
    "operation": "read",
    "binaryPropertyName": "data",
    "options": { "readAs": "binary" }
  },
  "position": [800, 300]
},

3.4 Inspect the parsed JSON

{
  "name": "Debug Output",
  "type": "n8n-nodes-base.debug",
  "typeVersion": 2,
  "parameters": { "output": "firstItemJson" },
  "position": [1100, 300]
},

3.5 Wire the nodes together

{
  "connections": {
    "HTTP Get XLSX": { "main": [[{ "node": "Set Binary Property", "type": "main", "index": 0 }]] },
    "Set Binary Property": { "main": [[{ "node": "Excel Read", "type": "main", "index": 0 }]] },
    "Excel Read": { "main": [[{ "node": "Debug Output", "type": "main", "index": 0 }]] }
  }
}

Why this works

• The HTTP node forces a binary stream (responseFormat: file).
• The Set node assigns the stream to a known property (data).
• The Excel node reads exactly that property, removing any ambiguity.

If the workflow still throws “File corrupted”, move on to the next sections.

---

4. Configuring the Excel node for read vs write

If you encounter any n8n wait node timeout resolve them before continuing.

Mode	Required settings	Typical pitfalls
Read	• Enable Read from Binary • Set Binary Property to the upstream name (e.g., data)	Forgetting to enable the flag → node looks for a file path that doesn’t exist.
Write	• Enable Write to Binary • Define Binary Property for the output (e.g., excelFile)	Overwriting an existing binary property without Keep Only Set can corrupt downstream nodes.
Both (CSV → XLSX)	Use a Set node to rename the CSV binary, then an Excel node with Write mode and Read from Binary disabled.	Mixing CSV MIME with XLSX output triggers “File corrupted”.

Example: Converting a CSV to XLSX in‑place

{
  "name": "Get CSV",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": { "url": "...", "responseFormat": "file" }
},
{
  "name": "Set CSV Binary",
  "type": "n8n-nodes-base.set",
  "parameters": { "binaryPropertyName": "csvData" },
  "keepOnlySet": true
},
{
  "name": "CSV → XLSX",
  "type": "n8n-nodes-base.excel",
  "parameters": {
    "operation": "write",
    "binaryPropertyName": "csvData",
    "options": {
      "writeAs": "xlsx",
      "outputBinaryProperty": "excelFile"
    }
  }
}

---

5. Permissions & temporary‑file handling (EEFA)

• Docker – mount a writable /tmp (-v /tmp:/tmp) or set N8N_TEMP_FOLDER=/custom/tmp.
• Kubernetes – attach an emptyDir volume at the path defined by N8N_TEMP_FOLDER.
• Quota checks – ensure the temp directory has enough free space (df -h /tmp).

EEFA warning: Low‑memory pods may cause ExcelJS to stream to disk. If the pod is OOM‑killed, a partial temp file remains and the next run fails with “corrupted”. Increase the pod’s memory limit or split the file into smaller chunks before processing.

---

6. Validation checklist before the Excel node

Check	How to verify
Binary exists	Debug node → binary object is not null.
Correct MIME	binary.mimeType === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" (XLSX) or text/csv.
Size < 100 MB (recommended)	binary.size < 104857600.
Read/write permission	ls -l $(npm root)/tmp – user n8n can read/write.
No trailing null bytes	Use a Function node to trim: Buffer.from(binary.data, 'base64').slice(0, -1).

---

7. Advanced troubleshooting – when the error persists

7.1 Inspect the raw buffer

Add a Function node after the source node:

const buf = Buffer.from($binary.data, 'base64');
const fs = require('fs');
fs.writeFileSync('/tmp/debug.xlsx', buf);
return [{ json: { message: 'Saved to /tmp/debug.xlsx' } }];

Download the file from the execution logs and open it in Excel. If Excel reports corruption, the source file itself is broken.

7.2 Force re‑encoding (UTF‑16 BOM issues)

const buf = Buffer.from($binary.data, 'base64');
const fixed = Buffer.from(buf.toString('utf16le'), 'utf8');
$binary.data = fixed.toString('base64');
return items;

7.3 Upgrade the bundled exceljs library

npm install exceljs@latest
# then restart the n8n service

---

8. Preventive measures for future workflows

• Always set a binary property name after any file‑fetching node.
• Normalise MIME types with a Set node: binary.mimeType = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet".
• Limit file size using an IF node that checks binary.size.
• Externalise large files (S3, Azure Blob) and feed only the URL to the Excel node via the “Read from URL” option (available in n8n > 0.210).

---

9. Frequently asked questions

Question	Answer
Why does the error appear only on the second run?	The first run creates a temp file that stays locked. Subsequent runs try to overwrite it and fail. Clean /tmp or configure N8N_TEMP_FOLDER to a unique per‑execution subfolder.
Can I process password‑protected XLSX files?	No – the built‑in Excel node does not support decryption. Use a custom JavaScript node with a library such as xlsx-populate that handles passwords.
Is the error caused by a corrupted download?	Often. Add a **Retry** strategy on the HTTP node (e.g., 3 retries with exponential back‑off) to mitigate flaky sources.

---

Conclusion

The “File corrupted” error is almost always traceable to a mismatch between the binary payload and what exceljs expects—whether that’s an incorrect MIME type, a missing binary property, a permission‑blocked temp folder, or a CSV masquerading as XLSX. By:

1. Normalising the binary property name,
2. Enabling the correct “Read/Write from Binary” mode,
3. Verifying MIME, size, and permissions, and
4. Converting CSVs before handing them to the Excel node,

you eliminate the root causes and make the workflow robust in any deployment environment. Apply the checklist, use the provided debugging snippets, and your n8n Excel node will handle workbooks reliably in production.