What causes "Failed to decode base64 attachment data" in n8n-io/n8n?

Confirm attachment.data is valid base64 (e.g. /^[A-Za-z0-9+/]*={0,2}$/ with correct padding) before calling parseStructuredFile.

n8n-io/n8n · error

Failed to decode base64 attachment data

Error message

Failed to decode base64 attachment data

What it means

Documented as the catch around Buffer.from(attachment.data, 'base64') inside parseStructuredFile (structured-file-parser.ts:377). Node's Buffer.from(string,'base64') does not throw on invalid input — it discards non-base64 characters — so in current Node versions this branch is effectively unreachable. It exists as a defensive guard against future runtime changes.

Source

Thrown at packages/@n8n/instance-ai/src/parsers/structured-file-parser.ts:376

		}
	}

	return { rawHeaders, allRows: parsed as Array<Record<string, unknown>> };
}

// ── Main parse function ─────────────────────────────────────────────────────

export function parseStructuredFile(
	attachment: AttachmentInfo,
	attachmentIndex: number,
	input: ParseFileInput,
): ParseFileOutput {
	// Decode base64
	let decoded: Buffer;
	try {
		decoded = Buffer.from(attachment.data, 'base64');
	} catch {
		throw new Error('Failed to decode base64 attachment data');
	}

	if (decoded.length > MAX_DECODED_SIZE_BYTES) {
		throw new Error(formatSizeLimitMessage(decoded.length));
	}

	const content = decoded.toString('utf-8');
	const format = detectFormat(attachment.fileName, attachment.mimeType, input.format);
	if (!format || !isLegacyTabularFormat(format)) {
		throw new Error(
			`Unsupported format for "${attachment.fileName}" (${attachment.mimeType}). Supported: csv, tsv, json`,
		);
	}

	const hasHeader = input.hasHeader ?? true;
	const startRow = input.startRow ?? 0;
	const maxRows = Math.min(input.maxRows ?? DEFAULT_MAX_ROWS, MAX_ROWS_PER_CALL);
	const warnings: string[] = [];

View on GitHub (pinned to 5ac6606e81)

Solutions

Confirm attachment.data is valid base64 (e.g. /^[A-Za-z0-9+/]*={0,2}$/ with correct padding) before calling parseStructuredFile.
Check the Node version and any Buffer polyfills in the runtime.
If genuinely hit, re-encode the source bytes to base64 before attaching.

Defensive patterns

Strategy: validation

Validate before calling

const BASE64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
if (typeof attachment.data !== 'string' || !BASE64_RE.test(attachment.data)) {
  throw new Error('attachment.data must be valid base64');
}

Type guard

function isBase64String(v: unknown): v is string {
  return typeof v === 'string' && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(v);
}

Try / catch

try { return parseStructuredFile(attachment, idx, input); }
catch (e) {
  if (e instanceof Error && e.message === 'Failed to decode base64 attachment data') {
    // re-encode the source bytes to base64 and retry
  }
  throw e;
}

Prevention

Always encode attachments with Buffer.from(bytes).toString('base64').
Validate base64 shape before sending if the source is untrusted.
Confirm Node's Buffer.from is not shimmed in the host environment.

When it happens

Trigger: Only reachable if a future Node version or Buffer polyfill makes Buffer.from throw for malformed base64. Today, malformed base64 silently produces a short/empty buffer instead.

Common situations: Practically never seen on supported Node versions. If observed, it indicates a non-standard Buffer shim or a host that wraps Buffer.from to validate strict base64.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/143c590b71de110f. Report an issue: GitHub.