{"record":{"id":"d515627eeb6047ae","repo":"n8n-io/n8n","slug":"xlsx-attachment-filename-sheet-firstsheetn","errorCode":null,"errorMessage":"xlsx \"${attachment.fileName}\" sheet \"${firstSheetName}\" is empty.","messagePattern":"xlsx \"(.+?)\" sheet \"(.+?)\" is empty\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@n8n/instance-ai/src/parsers/xlsx-parser.ts","lineNumber":51,"sourceCode":"\t\tworkbook = XLSX.read(decoded, { type: 'buffer' });\n\t} catch (error) {\n\t\tconst message = error instanceof Error ? error.message : 'unknown error';\n\t\tthrow new Error(`Failed to parse xlsx \"${attachment.fileName}\": ${message}`);\n\t}\n\n\tconst firstSheetName = workbook.SheetNames[0];\n\tif (!firstSheetName) {\n\t\tthrow new Error(`xlsx \"${attachment.fileName}\" has no sheets.`);\n\t}\n\n\tconst sheet = workbook.Sheets[firstSheetName];\n\tconst json = XLSX.utils.sheet_to_json<Record<string, unknown>>(sheet, {\n\t\tblankrows: false,\n\t\tdefval: null,\n\t});\n\n\tif (json.length === 0) {\n\t\tthrow new Error(`xlsx \"${attachment.fileName}\" sheet \"${firstSheetName}\" is empty.`);\n\t}\n\n\t// Round-trip through the JSON path of parseStructuredFile so types\n\t// (numbers, booleans) survive and we share row/column budget logic.\n\tconst jsonAttachment: AttachmentInfo = {\n\t\tdata: Buffer.from(JSON.stringify(json), 'utf-8').toString('base64'),\n\t\tmimeType: 'application/json',\n\t\tfileName: attachment.fileName,\n\t};\n\n\tconst result = parseStructuredFile(jsonAttachment, attachmentIndex, {\n\t\t...input,\n\t\tformat: 'json',\n\t});\n\n\t// Preserve original mime type and report xlsx as the format on output.\n\treturn { ...result, mimeType: attachment.mimeType, format: 'xlsx' };\n}","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/instance-ai/src/parsers/xlsx-parser.ts#L33-L69","documentation":"Thrown by extractXlsxAsRows (xlsx-parser.ts:50-52) when XLSX.utils.sheet_to_json returns an empty array for the first sheet. The sheet exists but contains no rows (blankrows: false collapses empty rows, so an all-blank sheet also triggers this). Distinct from error 510: the sheet is present, just has no data.","triggerScenarios":"The first sheet is entirely empty or contains only blank cells; the sheet has a header row but sheet_to_json with defval:null still yields no records because blankrows:false removed everything; only formatting/chart objects exist with no cell data.","commonSituations":"User exports a chart-only sheet; a sheet whose data was cleared but formatting kept; the real data lives on a non-first sheet (only SheetNames[0] is read).","solutions":["Move the data onto the first sheet, or delete empty preceding sheets so the data sheet becomes first.","Confirm the sheet has actual cell values, not just formatting.","If the data is on another sheet, reorder sheets so the populated one is first.","Attach the data directly as CSV/JSON instead."],"exampleFix":"// before: first sheet is blank, data is on sheet 2\n// after:  move data sheet to the first position, save, attach","handlingStrategy":"try-catch","validationCode":"// Pre-check the first sheet has rows\n// const json = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { blankrows: false, defval: null });\n// if (!json.length) throw new Error('first sheet is empty');","typeGuard":"function firstSheetHasRows(json: unknown[]): boolean {\n  return Array.isArray(json) && json.length > 0;\n}","tryCatchPattern":"try { return await extractXlsxAsRows(attachment, idx, input); }\ncatch (e) {\n  if (e instanceof Error && /sheet .* is empty\\.$/.test(e.message)) {\n    // request data on the first sheet or reorder sheets\n  }\n  throw e;\n}","preventionTips":["Put the data sheet first before exporting.","Clear formatting-only sheets so the populated one is first.","If only formatting exists, attach CSV/JSON instead."],"tags":["xlsx","empty-file","attachment-parsing","validation"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}