{"record":{"id":"c6fb145ab33e2737","repo":"heygen-com/hyperframes","slug":"engine-config-field-must-be-a-boolean","errorCode":null,"errorMessage":"Engine config ${field} must be a boolean","messagePattern":"Engine config (.+?) must be a boolean","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":464,"sourceCode":"    assertEngineConfigNumber(config, field, 0, true);\n  }\n}\n\nfunction validateEngineConfigVp9(config: Record<string, unknown>): void {\n  if (\n    typeof config.vp9CpuUsed !== \"number\" ||\n    !Number.isInteger(config.vp9CpuUsed) ||\n    config.vp9CpuUsed < -8 ||\n    config.vp9CpuUsed > 8\n  ) {\n    throw new Error(\"Engine config vp9CpuUsed must be an integer in [-8, 8]\");\n  }\n}\n\nfunction validateEngineConfigRuntime(config: Record<string, unknown>): void {\n  for (const field of BOOLEAN_ENGINE_CONFIG_FIELDS) {\n    if (typeof config[field] !== \"boolean\")\n      throw new Error(`Engine config ${field} must be a boolean`);\n  }\n  for (const field of POSITIVE_NUMBER_ENGINE_CONFIG_FIELDS) {\n    assertEngineConfigNumber(config, field, 1, field === \"frameDataUriCacheLimit\");\n  }\n  assertEngineConfigNumber(config, \"streamingEncodeMaxDurationSeconds\", 0);\n  assertEngineConfigNumber(config, \"audioGain\", 0);\n}\n\nfunction validateEngineConfigHdr(config: Record<string, unknown>): void {\n  const { hdr } = config;\n  if (\n    hdr !== false &&\n    (!isPlainObject(hdr) ||\n      Object.keys(hdr).length !== 1 ||\n      (hdr.transfer !== \"hlg\" && hdr.transfer !== \"pq\"))\n  ) {\n    throw new Error(\"Engine config hdr must be false or an hlg/pq transfer object\");\n  }","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L446-L482","documentation":"validateEngineConfigRuntime() requires every field in BOOLEAN_ENGINE_CONFIG_FIELDS to be a boolean. That set is: disableGpu, enableBrowserPool, forceScreenshot, staticFrameDedup, useDrawElement, enableDrawElementWorkerEncode, lowMemoryMode, enablePageSideCompositing, enableChunkedEncode, enableStreamingEncode, hdrAutoDetect, verifyRuntime, debug.","triggerScenarios":"validateEngineConfigSnapshot() receives one of those fields as a truthy non-boolean (\"true\" string, 1, undefined where a value was expected, null). Because required-field validation already confirmed presence, this fires when the value is the wrong primitive type.","commonSituations":"Env-var overrides parsed as strings (HF_DEBUG=1 -> \"1\"); JSON with quoted booleans; a config UI emitting 0/1 instead of false/true; deserializing from a format that lost the boolean type.","solutions":["Set the named field to a real boolean (true/false), not a string or number.","When reading env vars, coerce: `const debug = process.env.HF_DEBUG === \"true\"` (or parse {true,1,on}).","Run the snapshot through resolveConfig() which performs env coercion to booleans."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, debug: \"true\", disableGpu: 1 };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, debug: true, disableGpu: false };","handlingStrategy":"validation","validationCode":"const BOOLEAN_FIELDS = [\"disableGpu\",\"enableBrowserPool\",\"forceScreenshot\",\"staticFrameDedup\",\"useDrawElement\",\"enableDrawElementWorkerEncode\",\"lowMemoryMode\",\"enablePageSideCompositing\",\"enableChunkedEncode\",\"enableStreamingEncode\",\"hdrAutoDetect\",\"verifyRuntime\",\"debug\"] as const;\n\nfor (const f of BOOLEAN_FIELDS) {\n  if (typeof cfg[f] !== \"boolean\") throw new Error(`${f} must be a boolean`);\n}","typeGuard":"function allBooleanFieldsPresent(config: Record<string, unknown>): boolean {\n  return BOOLEAN_FIELDS.every((f) => typeof config[f] === \"boolean\");\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/must be a boolean/.test(String(e))) {\n    const field = String(e).match(/Engine config (\\w+) must be a boolean/)?.[1];\n    if (field) (snapshot as any)[field] = Boolean((snapshot as any)[field]);\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Coerce env-var booleans explicitly: `value === \"true\"` / parse {true,1,on}.","Use resolveConfig() which handles env coercion for booleans.","Emit real booleans (not 0/1 or \"true\") from config UIs."],"tags":["engine-config","validation","boolean","type-coercion"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}