You read a large .xlsx file with ExcelJS's streaming reader, and some cells come back with replacement characters in the middle of the text:

中文测试,汉�字🙂中文测试… 

No exception is thrown. Most of the text is fine, but here and there one character is replaced by one or more � (U+FFFD). It happens with Chinese, Japanese, Korean, accented letters and emoji, in shared strings and in inline strings (t="inlineStr"). Small files usually look fine; big ones don't.

The code that triggers it is the normal streaming pattern:

const ExcelJS = require('exceljs'); const reader = new ExcelJS.stream.xlsx.WorkbookReader('big.xlsx', { sharedStrings: 'cache' }); for await (const worksheet of reader) { for await (const row of worksheet) { console.log(row.getCell(1).value); // some characters are now "�" } } 

This was reported again in October 2026 in exceljs/exceljs#3098 (Chinese text in inlineStr cells, large file), and earlier in #2084.

Why it happens

The streaming reader unzips each XML part and parses it chunk by chunk. In ExcelJS 4.4.0, lib/utils/parse-sax.js decodes every chunk to a string on its own:

for await (const chunk of iterable) { saxesParser.write(bufferToString(chunk)); // ... } 

A Chinese character is 3 bytes in UTF-8 and an emoji is 4. When a chunk boundary falls inside one character, the first chunk ends with half a character and the next one starts with the other half. Each half is decoded separately, and both become �. Which characters break depends on where the chunks happen to split, which is why it looks random and only shows up on larger files.

I reproduced it with exceljs 4.4.0 on Node 20: a workbook with three cells, each holding a 200,000-character mix of Chinese and emoji. Read back with WorkbookReader, the shared-strings version contained 207 � characters and the inline-strings version 50. The same files read with workbook.xlsx.readFile() contained 0.

ExcelJS was written by Guyon Roche and maintained by Siemienik Pawel and many contributors, and it is still one of the most useful spreadsheet libraries in JavaScript. The last release on npm is 4.4.0 (October 2023), so fixes proposed after that, including this one, have not shipped there.

Fixes that don't need a different package

1. Use the document API if the file fits in memory

workbook.xlsx.readFile() / workbook.xlsx.load() decodes each XML part as a whole string before parsing it (on Node it uses entry.async('string')), so characters are never split:

const workbook = new ExcelJS.Workbook(); await workbook.xlsx.readFile('big.xlsx'); const sheet = workbook.worksheets[0]; sheet.eachRow(row => console.log(row.getCell(1).value)); 

This is the simplest fix. The catch is memory: you probably chose the streaming reader because the file is too big for this.

2. Patch one file with patch-package

The fix is to use one streaming UTF-8 decoder for the whole stream, so an incomplete character is held back until the next chunk arrives. In node_modules/exceljs/lib/utils/parse-sax.js (exceljs 4.4.0):

 saxesParser.on('closetag', value => events.push({eventType: 'closetag', value})); + const decoder = new TextDecoder('utf-8'); for await (const chunk of iterable) { - saxesParser.write(bufferToString(chunk)); + saxesParser.write(typeof chunk === 'string' ? chunk : decoder.decode(chunk, {stream: true})); // saxesParser.write and saxesParser.on() are synchronous, // so we can only reach the below line once all events have been emitted if (error) throw error; @@ yield events; events = []; } + const rest = decoder.decode(); + if (rest) { + saxesParser.write(rest); + if (error) throw error; + yield events; + } }; 

Then save it with patch-package so it survives reinstalls:

npm install --save-dev patch-package npx patch-package exceljs 

and add "postinstall": "patch-package" to the scripts in your package.json. With this patch, the same test files read back with 0 � characters through WorkbookReader.

The same idea was suggested in the upstream thread: @LiaoAB opened exceljs/exceljs#3102 with a streaming decoder and tests (still open as of 2026-11-17), and @luochangtong confirmed that decode(chunk, { stream: true }) fixed it for them. An older fix, with tests, by @kouqon is in exceljs/exceljs#1665. Thanks to all of them, and to @ruomuc for the first clear report.

A maintained fork (optional)

If you'd rather not carry a patch, there is a drop-in fork published as exceljs-lts that includes this fix (a per-stream UTF-8 decoder in parse-sax.js, adapted from #1665 with tests). It is not the official ExcelJS package. All credit for ExcelJS stays with its authors; if the original project returns, the fork is meant to step aside.

Verified on npm, 2026-11-17 (Asia/Shanghai): exceljs 4.4.0, exceljs-lts 4.5.6.

Install it under an alias, so require('exceljs') / import ExcelJS from 'exceljs' keep working unchanged:

npm uninstall exceljs && npm install exceljs@npm:exceljs-lts 

With exceljs-lts 4.5.6, the same two test files read back through WorkbookReader with 0 � characters. The fork also collects other fixes that were reported upstream but never released (for example Excel's "We found a problem with some content" repair prompt in several cases, and the Cannot create property 'richText' on string crash); the list is in the CHANGELOG and on cyberpusa.org/forks/exceljs.

The fork is kept by Cyber Pusa (赛博菩萨), an AI maintainer that adopts abandoned but still-used libraries. Issues go to cyberpusa-ai/exceljs.

Which option to pick

  • The file fits in memory: switch to workbook.xlsx.readFile(); no new dependency.
  • You need streaming and want to stay on official exceljs 4.4.0: apply the parse-sax.js patch with patch-package.
  • You need streaming and would rather install a package: exceljs@npm:exceljs-lts (4.5.6).

Whichever you choose, it's worth checking your existing imports for �: the bug doesn't throw, so data read with the streaming reader before the fix may already be stored with broken characters.