{"record":{"id":"b8395d91909830bc","repo":"actualbudget/actual","slug":"failed-to-create-sheet","errorCode":null,"errorMessage":"Failed to create sheet","messagePattern":"Failed to create sheet","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/desktop-client/src/hooks/useFormulaExecution.ts","lineNumber":105,"sourceCode":"}): FormulaCellValue {\n  let hfInstance: ReturnType<typeof HyperFormula.buildEmpty> | null = null;\n\n  try {\n    hfInstance = HyperFormula.buildEmpty({\n      licenseKey: 'gpl-v3',\n      language: 'enUS',\n      localeLang: typeof locale === 'string' ? locale : 'en-US',\n      dateFormats: ['DD/MM/YYYY', 'YYYY-MM-DD', 'YYYY/MM/DD'],\n      context: {\n        formulaQuery: formulaQueryContext,\n      },\n    });\n\n    const sheetName = hfInstance.addSheet('Sheet1');\n    const sheetId = hfInstance.getSheetId(sheetName);\n\n    if (sheetId === undefined) {\n      throw new Error('Failed to create sheet');\n    }\n\n    if (namedExpressions) {\n      for (const [name, value] of Object.entries(namedExpressions)) {\n        hfInstance.addNamedExpression(\n          name,\n          typeof value === 'number' ? value : String(value),\n        );\n      }\n    }\n\n    hfInstance.setCellContents({ sheet: sheetId, col: 0, row: 0 }, [[formula]]);\n\n    const cellValue = hfInstance.getCellValue({\n      sheet: sheetId,\n      col: 0,\n      row: 0,\n    });","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/actualbudget/actual/blob/d4334cb6e6123f4d3bcea1ad6166608884c7e658/packages/desktop-client/src/hooks/useFormulaExecution.ts#L87-L123","documentation":"evaluateFormulaWithContext builds a temporary HyperFormula instance to evaluate a single formula. It calls hfInstance.addSheet('Sheet1') and then checks getSheetId(sheetName); if HyperFormula did not register the sheet (undefined), the hook throws 'Failed to create sheet'. This indicates the HyperFormula engine rejected or failed to register the new sheet, usually due to an internal engine state problem or a misconfigured instance.","triggerScenarios":"Calling executeFormula/evaluateFormulaWithContext when the HyperFormula instance is in an invalid or protected state, when addSheet returns undefined due to engine build failures, or when a duplicate/invalid configuration causes sheet registration to fail.","commonSituations":"Passing malformed options to createHyperFormula; running in an environment where HyperFormula fails to initialize (e.g. missing polyfills); engine instance reuse bugs after destroy; HyperFormula version behavior changes around addSheet.","solutions":["Check that the HyperFormula instance is created successfully and not destroyed before addSheet is called","Verify the HyperFormula version supports addSheet/getSheetId as used, and pin/upgrade the dependency","Add logging or a try/catch around hfInstance creation to surface the underlying engine error","Report or guard: treat sheetId === undefined as a fallback by recreating the engine instance and retrying once"],"exampleFix":"// before\nconst hfInstance = createHyperFormula();\nconst sheetName = hfInstance.addSheet('Sheet1');\nconst sheetId = hfInstance.getSheetId(sheetName);\n// after\nlet hfInstance;\ntry {\n  hfInstance = createHyperFormula();\n} catch (err) {\n  throw new Error(`HyperFormula init failed: ${err.message}`);\n}\nconst sheetName = hfInstance.addSheet('Sheet1');\nconst sheetId = hfInstance.getSheetId(sheetName);\nif (sheetId === undefined) {\n  throw new Error(`Failed to create sheet: sheetName=${sheetName}`);\n}","handlingStrategy":"try-catch","validationCode":"let hf;\ntry {\n  hf = createHyperFormula();\n  if (typeof hf.addSheet !== 'function') throw new Error('HyperFormula API unavailable');\n} catch (err) {\n  throw new Error(`HyperFormula unavailable: ${err.message}`);\n}","typeGuard":"const isHyperFormulaInstance = (x: unknown): x is HyperFormula =>\n  !!x && typeof (x as HyperFormula).addSheet === 'function' && typeof (x as HyperFormula).getSheetId === 'function';","tryCatchPattern":"try {\n  const value = await executeFormula(formula);\n} catch (err) {\n  if (err.message === 'Failed to create sheet') {\n    // recreate engine or fall back to non-formula path\n  } else throw err;\n}","preventionTips":["Keep the HyperFormula instance lifecycle simple: create, use, destroy — never reuse a destroyed instance","Pin the HyperFormula version and check its changelog before upgrading","Log the underlying engine errors around addSheet to catch init problems early","Add a smoke test that evaluates a trivial formula in CI"],"tags":["hyperformula","spreadsheet","initialization"],"backgroundTag":"engine-initialization-failure","analyzedSha":"d4334cb6e6123f4d3bcea1ad6166608884c7e658","analyzedAt":"2026-08-29T01:02:11.213Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}