actualbudget/actual · error

Formula error: ${cellValue.type}

Error message

Formula error: ${cellValue.type}

What it means

After evaluating a formula, the hook checks isHyperFormulaError(cellValue) and, when throwOnCellError is enabled, throws 'Formula error: <type>'. HyperFormula represents formula failures (e.g. #DIV/0!, #NAME?, #REF!) as error-typed cell values rather than exceptions, so this surfaces those cell-level errors as a JavaScript error.

Source

Thrown at packages/desktop-client/src/hooks/useFormulaExecution.ts:127

      for (const [name, value] of Object.entries(namedExpressions)) {
        hfInstance.addNamedExpression(
          name,
          typeof value === 'number' ? value : String(value),
        );
      }
    }

    hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [[formula]]);

    const cellValue = hfInstance.getCellValue({
      sheet: sheetId,
      col: 0,
      row: 0,
    });

    if (isHyperFormulaError(cellValue)) {
      if (throwOnCellError) {
        throw new Error(`Formula error: ${cellValue.type}`);
      }
      return null;
    }

    return cellValue as FormulaCellValue;
  } finally {
    hfInstance?.destroy();
  }
}

export function useFormulaExecution(
  formula: string,
  queries: QueriesMap,
  queriesVersion?: number,
  namedExpressions?: Record<string, number | string>,
  accounts?: SimpleAccount[],
) {
  const locale = useLocale();

View on GitHub (pinned to d4334cb6e6)

Solutions

1. Fix the formula string to avoid the specific error type (validate function names and referenced cells)
2. Set throwOnCellError to false if a null result is acceptable for error-valued cells
3. Catch the error and inspect the type suffix to show a user-friendly message
4. Pre-validate the formula with HyperFormula's error-listing API before evaluating

Example fix

// before
const value = await executeFormula('=1/0', { throwOnCellError: true });
// after
let value;
try {
  value = await executeFormula('=IFERROR(1/0, 0)', { throwOnCellError: true });
} catch (err) {
  console.warn('Cell error:', err.message); // "Formula error: DIV_BY_ZERO"
  value = null;
}

const known = /^(SUM|IF|IFERROR|ROUND|DIVIDE)\s*\(/i;
if (!known.test(formula.trim())) console.warn('Formula uses unfamiliar function:', formula);

const isCellError = (v: CellValue): v is DetailedErrorCell =>
  typeof v === 'object' && v !== null && 'type' in v && 'value' in v && (v as any).type !== undefined;
// or reuse the hook's exported isHyperFormulaError(cellValue)

try {
  const value = await executeFormula(formula, { throwOnCellError: true });
} catch (err) {
  const match = /^Formula error: (.+)$/.exec(err.message);
  if (match) showFormulaErrorTooltip(match[1]); // e.g. DIV_BY_ZERO
  else throw err;
}

When it happens

Trigger: Evaluating a formula that produces a HyperFormula error value (DetailedErrorType such as DIV_BY_ZERO, NAME, REF, VALUE, CYCLE) while the caller set throwOnCellError to true.

Common situations: Typing a misspelled function name (#NAME?), dividing by zero or by an empty cell (#DIV/0!), referencing a deleted range (#REF!), or creating circular references in user-entered formulas.

Related errors

• Failed to create sheet
• Failed to create sheet
• Formula error: ${cellValue.message}
• Error loading data into the spreadsheet.
• Invalid BUDGET_QUERY dimension: ${dimension}

AI-assisted analysis of actualbudget/actual@d4334cb6e6 (2026-08-29). Data as JSON: /api/errors/01f27b29441d6624. Report an issue: GitHub.