{"record":{"id":"36facf3f39e0bc5e","repo":"actualbudget/actual","slug":"formula-error-cellvalue-message","errorCode":null,"errorMessage":"Formula error: ${cellValue.message}","messagePattern":"Formula error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/loot-core/src/server/rules/action.ts","lineNumber":356,"sourceCode":"          fieldValues[key] === undefined ||\n          fieldValues[key] === null ||\n          typeof fieldValues[key] === 'object'\n        ) {\n          cellValue = '';\n        } else {\n          cellValue = fieldValues[key];\n        }\n        hfInstance.addNamedExpression(key, cellValue);\n      }\n      hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [\n        [formula],\n      ]);\n\n      const cellAddress = { sheet: sheetId, col: 0, row: 0 };\n      const cellValue = hfInstance.getCellValue(cellAddress);\n\n      if (cellValue && typeof cellValue === 'object' && 'type' in cellValue) {\n        throw new Error(`Formula error: ${cellValue.message}`);\n      }\n\n      if (typeof cellValue === 'number') {\n        return amountToInteger(Math.round(cellValue * 100) / 100);\n      }\n\n      return cellValue;\n    } catch (err) {\n      logger.error('Formula execution error:', err);\n      throw err;\n    } finally {\n      try {\n        hfInstance?.destroy();\n      } catch (err) {\n        logger.error('Error destroying HyperFormula instance:', err);\n      }\n    }\n  }","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/actualbudget/actual/blob/d4334cb6e6123f4d3bcea1ad6166608884c7e658/packages/loot-core/src/server/rules/action.ts#L338-L374","documentation":"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!).","triggerScenarios":"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.","commonSituations":"Users writing formulas with wrong function names or unbalanced arguments; formulas referencing transaction fields that are empty/null; division operations with potentially zero denominators.","solutions":["Fix the formula text so it uses valid HyperFormula functions and operands","Guard against empty/null transaction fields feeding the formula (e.g. use IF or default values like '=IF(field=\"\",0,field)')","Avoid division by zero: wrap as '=IF(denominator=0,0,numerator/denominator)'"],"exampleFix":"// before\n\"=amount/total\" // errors when total is 0\n// after\n\"=IF(total=0,0,amount/total)\"","handlingStrategy":"try-catch","validationCode":"// sanity-check referenced fields before running\nif (transaction.amount == null || transaction.amount === 0) {\n  throw new Error('Referenced transaction field is empty/zero');\n}","typeGuard":"function isCellError(value: unknown): value is { type: string; message: string } {\n  return typeof value === 'object' && value !== null && 'type' in value;\n}","tryCatchPattern":"try {\n  const result = executeFormulaSync(formula, transaction);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Formula error:')) {\n    // show the HyperFormula diagnostic to the user for formula correction\n  } else throw e;\n}","preventionTips":["Wrap risky operations (division, date parsing) in IF() guards within the formula","Test formulas against edge-case transactions (empty fields, zero amounts)","Use only documented HyperFormula function names in the rule editor"],"tags":["formula","hyperformula","runtime-error"],"backgroundTag":"formula-evaluation-error","analyzedSha":"d4334cb6e6123f4d3bcea1ad6166608884c7e658","analyzedAt":"2026-08-29T01:02:11.213Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}