From 9dbfe8986bbba360212e4ec4d0707429829f9851 Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Tue, 8 Sep 2026 03:08:31 +0000 Subject: [PATCH 1/3] HF-131: document the SPILL error type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ErrorType has ten members; this guide's error table only listed nine. Add the missing #SPILL! row, matching the existing table's style, plus a short note that HyperFormula does not turn a message into a longer plain-language explanation itself — an application layer wanting that should build it on top of the type/message the engine already provides. Docs-only, no CHANGELOG entry per this repo's DoD. Co-Authored-By: Claude Sonnet 5 --- docs/guide/types-of-errors.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/guide/types-of-errors.md b/docs/guide/types-of-errors.md index 4c524877ee..d2a1d594b9 100644 --- a/docs/guide/types-of-errors.md +++ b/docs/guide/types-of-errors.md @@ -9,6 +9,7 @@ tags: - "#CYCLE!" - "#ERROR!" - "#LIC!" + - "#SPILL!" - division by zero --- @@ -37,4 +38,16 @@ according to the language settings. | #VALUE! | Wrong type of argument | It occurs when a formula tries to improperly use different types of data. For example, you will see this error when you will try to add a string to a number. | | #CYCLE! | Circular reference | It occurs when a formula refers to its own cell, both directly and indirectly. | | #ERROR! | An error occurred | It indicates that there is an unknown error in a formula. | -| #LIC! | Invalid license key | It occurs when the license key is invalid, expired, or missing. | \ No newline at end of file +| #LIC! | Invalid license key | It occurs when the license key is invalid, expired, or missing. | +| #SPILL! | No space for array result | It occurs when an array formula's result would overwrite one or more non-empty cells, so it has nowhere to spill into. | + +## Error messages and explanations + +An error's `message` property states the specific cause within its type — for +example, distinguishing *why* a formula returned `#NUM!` rather than only that it +did. HyperFormula does not turn that message into a longer, plain-language +explanation, and does not call out to a language model to generate one. An +application built on top of HyperFormula that wants to rephrase an error for its +end users — in natural language, or translated beyond the languages HyperFormula +ships with — should do so at the application layer, using the `type` and +`message` HyperFormula already provides as its input. \ No newline at end of file From 756cb081a222b5d08d25831113864b84573f2a20 Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Mon, 14 Sep 2026 10:07:51 +0000 Subject: [PATCH 2/3] HF-131: document how to find out where an error came from The page listed the error types but never mentioned originFunction, argumentIndex or hasMessage, so the only description of them was in the API reference. Also drops one tag: the page carried 11 against the guide's cap of 10, and 'division by zero' is the one tag that is a phrase rather than an error code, already covered by '#DIV/0!'. Co-Authored-By: Claude Opus 5 (1M context) --- docs/guide/types-of-errors.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/guide/types-of-errors.md b/docs/guide/types-of-errors.md index d2a1d594b9..414875a2ec 100644 --- a/docs/guide/types-of-errors.md +++ b/docs/guide/types-of-errors.md @@ -10,7 +10,6 @@ tags: - "#ERROR!" - "#LIC!" - "#SPILL!" - - division by zero --- # Types of errors @@ -50,4 +49,27 @@ explanation, and does not call out to a language model to generate one. An application built on top of HyperFormula that wants to rephrase an error for its end users — in natural language, or translated beyond the languages HyperFormula ships with — should do so at the application layer, using the `type` and -`message` HyperFormula already provides as its input. \ No newline at end of file +`message` HyperFormula already provides as its input. + +## Finding out where an error came from + +Besides `type` and `message`, a `DetailedCellError` tells you what produced the +error and, when it was a function rejecting one of its own arguments, which +argument. `originFunction` names a function or an operator helper when one of them +rejected a value, and otherwise names what built the error: `reference` for a +reference that cannot be resolved, `removed reference` for one destroyed by +removing rows or columns, `parser` for a formula that could not be parsed, `user +input` for an error value typed into a cell, or `literal` for one written into a +formula. `argumentIndex` is zero-based. + +```javascript +const hf = HyperFormula.buildFromArray([['=SUM(SQRT(-1))'], ['=DATE(2000, "x", 1)'], ['=SUM(A99999999999:A99999999999)']]); + +hf.getCellValue({ sheet: 0, col: 0, row: 0 }).originFunction; // 'SQRT', not 'SUM' +hf.getCellValue({ sheet: 0, col: 0, row: 1 }).argumentIndex; // 1, the second argument +hf.getCellValue({ sheet: 0, col: 0, row: 2 }).originFunction; // 'reference' +``` + +The first occurrence wins, so a function that only read an error never replaces +the identity already on it. `address` points at the cell where the error arose, +which is not always the cell you read it from. \ No newline at end of file From d236c93305727642ef83987dcdd2b5aea8bbc2c0 Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Fri, 23 Oct 2026 00:23:43 +0000 Subject: [PATCH 3/3] HF-131: Make the error-origin example runnable as pasted, and list array literal The example now passes a license key, so the three formulas return the documented values instead of `#LIC!`, writes cell addresses as `{ sheet, row, col }`, and the list of origin names includes `array literal`. Co-Authored-By: Claude Opus 5.5 --- docs/guide/types-of-errors.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/guide/types-of-errors.md b/docs/guide/types-of-errors.md index 872746ab3e..216387a3c9 100644 --- a/docs/guide/types-of-errors.md +++ b/docs/guide/types-of-errors.md @@ -59,15 +59,19 @@ argument. `originFunction` names a function or an operator helper when one of th rejected a value, and otherwise names what built the error: `reference` for a reference that cannot be resolved, `removed reference` for one destroyed by removing rows or columns, `parser` for a formula that could not be parsed, `user -input` for an error value typed into a cell, or `literal` for one written into a -formula. `argumentIndex` is zero-based. +input` for an error value typed into a cell, `literal` for one written into a +formula, or `array literal` for an array literal whose rows differ in length. +`argumentIndex` is zero-based. ```javascript -const hf = HyperFormula.buildFromArray([['=SUM(SQRT(-1))'], ['=DATE(2000, "x", 1)'], ['=SUM(A99999999999:A99999999999)']]); +const hf = HyperFormula.buildFromArray( + [['=SUM(SQRT(-1))'], ['=DATE(2000, "x", 1)'], ['=SUM(A99999999999:A99999999999)']], + { licenseKey: 'gpl-v3' } +); -hf.getCellValue({ sheet: 0, col: 0, row: 0 }).originFunction; // 'SQRT', not 'SUM' -hf.getCellValue({ sheet: 0, col: 0, row: 1 }).argumentIndex; // 1, the second argument -hf.getCellValue({ sheet: 0, col: 0, row: 2 }).originFunction; // 'reference' +hf.getCellValue({ sheet: 0, row: 0, col: 0 }).originFunction; // 'SQRT', not 'SUM' +hf.getCellValue({ sheet: 0, row: 1, col: 0 }).argumentIndex; // 1, the second argument +hf.getCellValue({ sheet: 0, row: 2, col: 0 }).originFunction; // 'reference' ``` The first occurrence wins, so a function that only read an error never replaces