Skip to content
Docs: TroubleshootingMenu

Troubleshooting

Known Hypaxel limits and fixes: reader errors and upload limits, WebAssembly in the browser, ExcelJS, Excel size limits, dates and time zones, write order.

v0.3.0 unreleasedLast updated View as Markdown

Most problems with a streaming writer come from the same root: the file is written front to back and never revisited. The readers have the opposite constraint: they take the file as it is and reject what is not an XLSX workbook. This page lists the issues and limits documented for Hypaxel, each with its symptom, cause and fix. If something is not covered here, report it at github.com/vensas/hypaxel/issues.

ExcelJS cannot read the file#

Symptom. Excel, LibreOffice, openpyxl, calamine and others open the file, but reading it with ExcelJS fails.

Cause. By default Hypaxel omits cell references (r="B7") that follow from a cell’s position. That is valid and makes files smaller and faster to write, but ExcelJS requires a reference on every cell.

Fix. Turn on cell references for files that ExcelJS will read:

LanguageOption
.NETWriteCellReferences = true
Rust.cell_references(true)
Node.jscellReferences: true
GoWithCellReferences(true)
JavacellReferences(true)
PHPcellReferences: true

The PHP implementation already writes references after an empty cell and after a skipped row, which is what PhpSpreadsheet needs.

Go: xlsxreader or tealeg/xlsx misreads the file#

Symptom. A file written by Hypaxel for Go opens in Excel, but thedatashed/xlsxreader or tealeg/xlsx reads cells in the wrong place or fails.

Cause. Like ExcelJS, these readers need a cell reference on every cell. Excel, LibreOffice, excelize, openpyxl, calamine and Hypaxel’s own reader do not.

Fix. Write the file with hypaxel.NewWriter(dst, hypaxel.WithCellReferences(true)).

Excel limits exceeded#

Symptom. A write fails with an error about text length, columns or rows.

Cause. Excel limits apply: 1,048,576 rows, 16,384 columns and 32,767 characters per cell. Worksheet names have at most 31 characters.

Fix. Split long text or wide data, or spread rows across several worksheets. How the error surfaces depends on the language, and in each case the file stays valid:

  • Rust: cell methods are infallible; the next end_row, add_row or finish reports the problem and the offending cell is left empty.
  • Python: text over 32,767 characters raises XlsxError; the cell is left empty.
  • Node.js: exceeding the limits throws an XlsxError.
  • Go: later calls return the recorded error; test with errors.Is for ErrTextTooLong, ErrTooManyColumns or ErrRowOutOfRange. After a cell-level error the output is incomplete and must be discarded.
  • Java: an XlsxException whose kind() is for example TEXT_TOO_LONG. A rejected cell writes nothing.
  • PHP: a LimitExceededException. A row rejected by writeRow or writeRows is not written at all, so you can catch the exception and continue.

Formulas show no value until opened in Excel#

Symptom. A formula cell has no computed value when the file is processed by a tool that does not calculate formulas.

Cause. Formulas are stored without cached results. Excel recalculates them when the file opens.

Fix. If a downstream system needs the value, write the computed value as a plain cell in addition to, or instead of, the formula.

Dates are shifted or show the wrong time zone#

Symptom. Times in the sheet differ from what you expected by a few hours.

Cause. Excel has no time zones; a cell holds a wall-clock date and time. Each implementation decides which wall-clock time to write:

  • Node.js: a Date is written in the process time zone (dates: 'local', the default) or in UTC (dates: 'utc').
  • Go: a time.Time is written as the wall-clock time of its location.
  • Java: ZonedDateTime and OffsetDateTime keep their own local time; Instant and java.util.Date are converted in the zone option, by default the system default zone at the time the writer is created.
  • PHP: a DateTimeInterface is written as the wall-clock time of its own time zone.
  • Python: timezone-aware datetime values are written as local time.

Fix. Convert values to the zone you want before writing (t.UTC() or t.In(loc) in Go, setTimezone() in PHP), or set the dates option (Node.js) or zone option (Java).

Old dates appear as text#

Symptom. Dates before 1900 (or before 1904 with the 1904 date system, or after 9999 in Java and PHP) appear as text instead of dates.

Cause. Excel’s date systems cannot represent them, so Hypaxel writes them as ISO 8601 text.

Fix. None needed if text is acceptable. Otherwise store such values in a separate numeric or text column that suits your use.

9999-12-31 is text with the 1904 date system#

Symptom. With the 1904 date system, the date 9999-12-31 appears as text instead of a date (Rust and .NET, before 0.3.0).

Cause. A bug in 0.2.0 and earlier.

Fix. Upgrade to 0.3.0, where it is written as a date.

Unexpected date or number formats#

Symptom. Dates show in a different format on another computer.

Cause. Unstyled dates get the viewer’s locale date format.

Fix. Give the cell or column an explicit number format such as yyyy-mm-dd.

Large integers lose precision#

Symptom. Long IDs or bigint values end in different digits after opening the file.

Cause. Excel stores every number as a double. Integers beyond ±2^53 (and, in Java, BigDecimal values with more than 15 significant digits) lose precision. Node.js writes bigint as doubles.

Fix. Write such values as text when exactness matters.

Write order errors#

Symptom. Writing a row fails with a row-order error (for example ErrRowOrder in Go), or a cell ends up somewhere else than intended.

Cause. Rows are written top to bottom and cells left to right. You cannot go back to an earlier row.

Fix. Sort your data before writing. To leave gaps, skip cells or rows, or begin a row at a later row number: SkipCells / SkipRows / BeginRow(n) in .NET, skip_cells / skip_rows / begin_row_at in Rust, skipCells / skipRows / beginRowAt in Java and PHP, BeginRow(RowOptions{Index: ...}) in Go.

Cannot write to an earlier worksheet#

Symptom. Writing to a worksheet fails after another worksheet was added (for example ErrSheetClosed in Go).

Cause. One worksheet is open at a time. Adding the next worksheet completes the previous one.

Fix. Write each worksheet completely before adding the next one. If several sheets need data from the same source, read the source once per sheet or collect the smaller sheet first.

Column widths or frozen panes cannot be set later#

Symptom. There is no way to change column widths, frozen panes or the outline depth after rows have been written.

Cause. These settings come before the cell data in the file.

Fix. Pass them in the worksheet options when you create the sheet, or use auto-fit to size columns from the data. Merged cells, auto filters and tables can be added at any time before the sheet completes.

Row outline level rejected#

Symptom. Grouping a row fails (PHP throws an InvalidArgumentException), or the outline does not show as expected.

Cause. Excel reads the deepest outline level before the rows, so it must be declared up front.

Fix. Set the row outline levels option (RowOutlineLevels, row_outline_levels, rowOutlineLevels) to the deepest level you will use when adding the worksheet.

Excel repairs the file after adding a table#

Symptom. Excel reports a problem with the table or repairs the file, or adding the table throws.

Cause. With a header row, the table’s column names must equal the header texts exactly as written, because Excel identifies table columns by them. Table names must be unique in the workbook and follow Excel’s name rules, and tables cannot overlap each other, merged cells or the worksheet auto filter.

Fix. Pass the exact header texts as columns, choose a unique name, and make sure the range does not overlap other tables, merges or the auto filter.

Auto-fit delays the first bytes#

Symptom. With auto-fit enabled, a download does not start immediately.

Cause. Column widths come before the cell data in the file, so the writer holds back the sheet’s output until the sample has been measured: 1,000 rows by default, at most 8 MiB of XML.

Fix. Lower the sample size (SampleRows, sample_rows, autofit_sample_rows, sampleRows), set explicit column widths instead, or accept the short delay. Rows after the sample are not measured, and formulas are not measured at all.

Memory grows with shared strings#

Symptom. Memory use grows with the number of rows although Hypaxel is supposed to be constant-memory.

Cause. The shared string table keeps every distinct string until the workbook is finished. With one unique string per row, memory grows with the row count.

Fix. Use the default inline string storage unless your text is highly repetitive and file size matters more than memory.

Node.js and PHP in-memory writers grow#

Symptom. Memory grows while writing a large workbook with new Writer() (Node.js) or Writer::inMemory() (PHP), or with Xlsx::toString().

Cause. These writers keep their output in memory until you take it.

Fix. Call drain() between batches of rows and send the bytes on, or use a streaming helper (stream(), webStream(), Xlsx::stream(), Xlsx::output()) or a file or stream destination.

Java: client receives a complete-looking file with missing rows#

Symptom. An export fails half-way, but the client still receives a valid workbook that is missing rows.

Cause. Closing the writer completes the workbook, also when try-with-resources closes it because of an exception.

Fix. Call abort() when the export fails, so that the download is truncated and Excel rejects it:

XlsxWriter writer = XlsxWriter.create(response.getOutputStream());
try {
    writer.writeWorksheet("Orders", Order.class, orders);
    writer.close();
} catch (RuntimeException | IOException e) {
    writer.abort();
    throw e;
}

When the destination itself fails (the client disconnects), the writer aborts on its own.

Java: Spring stream fails outside a transaction#

Symptom. Reading a repository Stream inside a StreamingResponseBody fails.

Cause. A Stream backed by a database cursor needs an open transaction for as long as it is read.

Fix. With Spring Data, read it inside a read-only TransactionTemplate in the StreamingResponseBody.

Java: mapped type is not accessible#

Symptom. Object mapping fails for your record or class when running on the module path.

Cause. The mapped type must be accessible to the module de.vensas.hypaxel.

Fix. Make the type public in an exported package, or open its package to de.vensas.hypaxel. On the class path every type works.

Go: export failed after part of the file was sent#

Symptom. hypaxelhttp.Serve returns an error, and writing an error response does not work.

Cause. Part of the workbook had already been sent; the error wraps hypaxelhttp.ErrPartial. hypaxelhttp.Handler aborts the connection with http.ErrAbortHandler in this case, so the browser reports a failed download instead of saving a truncated file.

Fix. Only write an error response when errors.Is(err, hypaxelhttp.ErrPartial) is false.

Rust axum: download aborts with an error#

Symptom. A download ends with a network error instead of completing.

Cause. If the producer fails after streaming has started, the body ends with an error on purpose, so the client sees an aborted download instead of a silently truncated file.

Fix. Check the server logs for the producer’s error. Disconnects stop generation on the server side automatically.

Python: exports and the GIL#

Symptom. Other Python threads make little progress while a large export runs.

Cause. The GIL is held while writing, because values are read from Python objects.

Fix. Use threads for parallel exports of separate files.

Go: excelize shows no fill or border colors#

Symptom. Reading styles back with excelize returns empty fill and border colors.

Cause. Hypaxel writes no theme part, and excelize 2.11 returns empty fill and border colors for such workbooks.

Fix. None needed: the colors are in the file, and other readers show them.

PHP: download does not start until the export finishes#

Symptom. The browser waits for the whole file, or memory grows on the server or proxy.

Cause. Something between Hypaxel and the client collects the response.

Fix. Turn off zlib.output_compression and user-level output buffering for the request (.xlsx is already compressed), and tell a buffering proxy such as nginx to pass the response through, for example with the X-Accel-Buffering: no header.

PHP: UnsupportedValueException for a DateInterval#

Symptom. Writing a DateInterval throws UnsupportedValueException.

Cause. A duration needs a fixed length, and a month has no fixed number of days.

Fix. Use an interval from diff(), or one without years and months.

.NET: BeginRow(null) no longer compiles#

Symptom. After upgrading to 0.2.0, sheet.BeginRow(null) fails to compile.

Cause. A literal null is ambiguous with the new BeginRow(RowOptions) overload.

Fix. Call BeginRow() without arguments, or pass a RowOptions instance.

Writers and styles across threads#

Symptom. Errors or corrupted output when one writer is used from several threads, or a style from one writer is used with another.

Cause. A writer and its worksheets are not safe for concurrent use (documented for Go and Java), and styles belong to the writer that created them.

Fix. Use one writer per export and register styles on that writer. Separate writers are independent.

Reader rejects the file#

Symptom. Opening a workbook for reading fails right away, or reading a sheet fails part-way through.

Cause. The readers only read XLSX workbooks. A legacy .xls file, a password-protected (encrypted) workbook, a CSV file or another document such as a Word file is not one; the error names what the file is. A damaged part (invalid XML, a bad cell value, a ZIP entry that fails its size or CRC check) fails when it is read, and the error names the part. The error types are:

LanguageNot an XLSX workbookDamaged partSheet not found
.NETXlsxReadException, Kind InvalidFileXlsxReadException, Kind Malformed, with PartKeyNotFoundException (by name), ArgumentOutOfRangeException (by index)
RustError::InvalidFileError::Malformed { part, message }Error::SheetNotFound
PythonXlsxErrorXlsxErrorXlsxError (the message lists the sheets)
GoErrInvalidFileErrMalformed, in a *ReadError with PartErrSheetNotFound
JavaXlsxException, kind() INVALID_FILEXlsxException, kind() MALFORMED, with part()XlsxException, kind() SHEET_NOT_FOUND

Python raises FileNotFoundError for a missing path. In Go, test with errors.Is. In .NET, Go and Java, a chart sheet or another feature the reader does not support gives Unsupported, ErrUnsupported or UNSUPPORTED.

Fix. Catch the error and report it to the user: ask for the file to be saved as .xlsx (Excel Workbook) without a password, and read CSV with a CSV parser. Node.js and PHP do not read files yet.

Untrusted uploads and the shared string table#

Symptom. Reading an uploaded file uses much more memory than one row, or fails with a limit error.

Cause. Rows are streamed, but the shared string table (text that a workbook stores once) is held in memory while a sheet is read. Its default cap is 1 GiB. Every XML token and row is bounded as well, and DTDs are rejected.

Fix. Lower the cap for files you do not control:

LanguageOptionError when exceeded
.NETnew XlsxReaderOptions { MaxSharedStringsBytes = ... }XlsxReadException, Kind LimitExceeded
RustReadOptions::new().max_shared_strings_bytes(n) with XlsxReader::open_with or with_optionsError::LimitExceeded
Pythonopen_workbook(source, max_shared_strings_bytes=n); the one-call readers take it tooXlsxError
Gohypaxel.WithMaxSharedStringsBytes(n)ErrLimitExceeded
JavaReadOptions.builder().maxSharedStringsBytes(n).build()XlsxException, kind() LIMIT_EXCEEDED

In Python, bytes and file objects are also held in memory once; a path is read from disk.

Reader does not return formulas, styles or merged cells#

Symptom. A formula cell reads as a number or text, a never-calculated formula reads as empty, and formatting is missing.

Cause. The readers return cell values. A formula yields its cached result, and a formula that was never calculated has no value. Formula text, styles (other than recognising dates from the number format), merged ranges, comments and hyperlinks are not read; the .NET reader also skips data validation.

Fix. None in 0.3.0; these parts are not read yet. If you need them, use a library that loads the whole workbook.

.NET: “The stream must be readable and seekable”#

Symptom. new XlsxReader(stream) throws an ArgumentException for a request body or another forward-only stream.

Cause. The ZIP directory is at the end of the file, so the reader must seek.

Fix. Copy the stream into a MemoryStream or a temporary file first, or use XlsxReader.Open(path). Reading is synchronous.

Java: rows change after reading the next one#

Symptom. Rows collected from nextRow() or a for (Row row : sheet) loop all show the values of the last row.

Cause. SheetReader.nextRow() and its iterator reuse one Row object, which is valid only until the next row is read.

Fix. Keep row.copy(), row.toList() or the values you need, or use stream(), which yields independent copies.

Java: reading an InputStream uses a lot of memory#

Symptom. Memory grows with the file size when reading from an InputStream.

Cause. The XLSX directory is at the end of the file, so XlsxReader.open(InputStream) reads the whole stream into memory first.

Fix. Pass a Path (or a SeekableByteChannel) for large files, for example after saving an upload to a temporary file.

Browser: XlsxError from new Writer() or toBufferSync#

Symptom. In a browser or another WebAssembly runtime, new Writer() or toBufferSync throws an XlsxError: the WebAssembly engine is not loaded.

Cause. The WebAssembly module loads on first use. toBlob, toBuffer and webStream load it themselves, but new Writer() and toBufferSync are synchronous and cannot.

Fix. Call await init() once before them, or initSync(bytes) in workers and server runtimes that read the file from disk. In Node.js init() resolves immediately, so shared code can always call it.

Browser: the WebAssembly module does not load#

Symptom. init() fails with “failed to load the WebAssembly engine”, for example under a strict Content Security Policy, or when the module should come from a CDN.

Cause. By default hypaxel_bg.wasm is fetched from next to the JavaScript file.

Fix. Serve the file from a location your policy allows and pass its URL or bytes: await init('/assets/hypaxel_bg.wasm'). The file is exported as hypaxel/hypaxel_bg.wasm. Runtimes that import .wasm files as compiled modules (Cloudflare Workers, for example) can pass the module to init. See Loading the WebAssembly module.

Browser: large exports use a lot of memory#

Symptom. A large export in the browser uses a lot of memory.

Cause. toBlob, toBuffer and an in-memory Writer hold the finished file in memory, compressed.

Fix. Use webStream and write it to disk, for example through the File System Access API (showSaveFilePicker() and pipeTo). webStream is pull-based, so rows are produced only as the file is written. See Large exports in the browser.