dc/.agent/skills/hyperformula/references/error-handling.md

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.

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

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 for the full pattern.

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