My XLSX converter shipped a due date as 45852 - Excel dates are serial numbers, not strings

The Bug

I spotted this while testing a client's invoice pipeline: a spreadsheet whose "Due date" column displayed 14/07/2025 in Excel. My converter's Markdown output listed 45852. Not a rendering bug - that's literally what the file stores. The stored value and the displayed value in a spreadsheet are two different things.

Why Excel Dates Are Serial Numbers

Excel keeps dates as serial numbers: days elapsed since 1899-12-30. The odd anchor is a relic of Lotus 1-2-3, which believed 1900 was a leap year, so Excel pretends 1900-02-29 exists and serial 60 points at a date that never happened. The friendly dd/mm/yyyy you see lives in styles.xml as a number-format code attached to the cell's style - the sheet data just holds the raw float.

Other formats share the same trap:

• Percentages: 0.175 stored, "17.5%" displayed.
• Booleans: stored as 1 and 0.

So an agent reading my output had no way to know 45852 was a deadline. One downstream job happily treated it as a quantity and scheduled a reorder around it.

The Fix

The fix: read each cell's style, check the format code for date/time patterns, then convert serial → datetime using the 1899-12-30 anchor - plus handling the 1904 date-system flag some Mac-era workbooks set, which shifts everything by 1,462 days. Fractional serials carry time-of-day, so I floor for pure dates and keep the time when the format asks for it.

Output now reads 2025-07-14 instead of 45852, and percentage cells render the human-facing value end-to-end on the invoice file that started it.

Tool and Takeaway

I shipped the fix in my XLSX-to-Markdown converter (https://x402.freeq.one/tools/xlsx_to_markdown.html), which also returns a JSON array of row objects.

The takeaway for anyone feeding spreadsheets into RAG or agent pipelines: never print raw cell values. Parse the style first, or your agent will file your deadline under line items.