70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# Error Handling
|
|
|
|
Inspect cell values that may be errors, tell error types apart, and check value shape. Authoritative docs:
|
|
- Types of errors: https://hyperformula.handsontable.com/docs/guide/types-of-errors.html
|
|
- Types of values: https://hyperformula.handsontable.com/docs/guide/types-of-values.html
|
|
|
|
## Always check `CellError` before using a result
|
|
|
|
Cell values can be errors (`#DIV/0!`, `#VALUE!`, `#REF!`, etc.). Always test before using a result.
|
|
|
|
```ts
|
|
import { CellError, ErrorType } from 'hyperformula';
|
|
|
|
const value = hf.getCellValue({ sheet: 0, col: 0, row: 0 });
|
|
|
|
if (value instanceof CellError) {
|
|
// ErrorType enum: DIV_BY_ZERO, VALUE, REF, NAME, NUM, NA, CYCLE, ERROR
|
|
switch (value.type) {
|
|
case ErrorType.CYCLE:
|
|
console.log('Circular reference');
|
|
break;
|
|
case ErrorType.NAME:
|
|
// Usually: function not registered (check plugin registration or i18n language)
|
|
console.log('Unknown name:', value.message);
|
|
break;
|
|
default:
|
|
console.log('Error:', value.type, value.message);
|
|
}
|
|
} else {
|
|
console.log('Value:', value);
|
|
}
|
|
```
|
|
|
|
## `#CYCLE!` is HyperFormula-specific
|
|
|
|
Standard spreadsheet apps report cycles differently. HyperFormula's `IF` also reports cycles for all branches, even unreachable ones — this can produce `#CYCLE!` in formulas that Excel or Sheets would evaluate.
|
|
|
|
## Inspect value shape without catching errors
|
|
|
|
```ts
|
|
import { CellValueDetailedType } from 'hyperformula';
|
|
|
|
hf.getCellValueDetailedType({ sheet: 0, col: 0, row: 0 });
|
|
// → CellValueDetailedType.NUMBER | STRING | BOOLEAN | ERROR | EMPTY | ...
|
|
```
|
|
|
|
Use the detailed type when you need to distinguish e.g. number vs empty without touching the value.
|
|
|
|
## Returning errors from custom functions
|
|
|
|
Custom `FunctionPlugin` methods can return a `CellError` to surface a formula error. See [custom-functions.md](custom-functions.md) for the full pattern.
|
|
|
|
```ts
|
|
import { CellError, ErrorType } from 'hyperformula';
|
|
|
|
return new CellError(ErrorType.DIV_BY_ZERO);
|
|
```
|
|
|
|
## Common causes
|
|
|
|
| Error | Common cause |
|
|
|---|---|
|
|
| `#NAME?` | Function not registered (check `registerFunctionPlugin` order or `language` config) |
|
|
| `#CYCLE!` | Circular reference — or an `IF` branch that *could* produce one |
|
|
| `#REF!` | Deleted row/column broke a formula reference |
|
|
| `#VALUE!` | Type mismatch — e.g. passing a string where a number is expected |
|
|
| `#DIV/0!` | Division by zero, including empty cells coerced to 0 |
|
|
| `#NUM!` | Out-of-range numeric result (e.g. `SQRT(-1)`) |
|
|
| `#N/A` | Lookup miss (`MATCH`, `VLOOKUP`) or propagated from an upstream `#N/A` |
|