actualbudget/actual · error

Formula error: ${cellValue.message}

Error message

Formula error: ${cellValue.message}

What it means

After setting the transaction field values into the sheet and computing cell A0, the code checks whether HyperFormula returned an error object (detected via a 'type' property) instead of a plain value. If so, it throws 'Formula error: <message>' with HyperFormula's own diagnostic (e.g. #DIV/0!, #NAME?, #VALUE!).

Source

Thrown at packages/loot-core/src/server/rules/action.ts:356

          fieldValues[key] === undefined ||
          fieldValues[key] === null ||
          typeof fieldValues[key] === 'object'
        ) {
          cellValue = '';
        } else {
          cellValue = fieldValues[key];
        }
        hfInstance.addNamedExpression(key, cellValue);
      }
      hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [
        [formula],
      ]);

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

      if (cellValue && typeof cellValue === 'object' && 'type' in cellValue) {
        throw new Error(`Formula error: ${cellValue.message}`);
      }

      if (typeof cellValue === 'number') {
        return amountToInteger(Math.round(cellValue * 100) / 100);
      }

      return cellValue;
    } catch (err) {
      logger.error('Formula execution error:', err);
      throw err;
    } finally {
      try {
        hfInstance?.destroy();
      } catch (err) {
        logger.error('Error destroying HyperFormula instance:', err);
      }
    }
  }

View on GitHub (pinned to d4334cb6e6)

Solutions

  1. Fix the formula text so it uses valid HyperFormula functions and operands
  2. Guard against empty/null transaction fields feeding the formula (e.g. use IF or default values like '=IF(field="",0,field)')
  3. Avoid division by zero: wrap as '=IF(denominator=0,0,numerator/denominator)'

Example fix

// before
"=amount/total" // errors when total is 0
// after
"=IF(total=0,0,amount/total)"
Defensive patterns

Strategy: try-catch

Validate before calling

// sanity-check referenced fields before running
if (transaction.amount == null || transaction.amount === 0) {
  throw new Error('Referenced transaction field is empty/zero');
}

Type guard

function isCellError(value: unknown): value is { type: string; message: string } {
  return typeof value === 'object' && value !== null && 'type' in value;
}

Try / catch

try {
  const result = executeFormulaSync(formula, transaction);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Formula error:')) {
    // show the HyperFormula diagnostic to the user for formula correction
  } else throw e;
}

Prevention

When it happens

Trigger: The formula evaluates to a HyperFormula error cell — e.g. '=A1/0' (division by zero), unknown function names ('=foo(1)' -> #NAME?), type mismatches ('=1+"a"' -> #VALUE?), or references to empty/invalid cells producing errors.

Common situations: Users writing formulas with wrong function names or unbalanced arguments; formulas referencing transaction fields that are empty/null; division operations with potentially zero denominators.

Related errors

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