What causes "Engine config ${field} must be a boolean" in heygen-com/hyperframes?

Set the named field to a real boolean (true/false), not a string or number.

heygen-com/hyperframes · error · Error

Engine config ${field} must be a boolean

Error message

Engine config ${field} must be a boolean

What it means

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.

Source

Thrown at packages/engine/src/config.ts:464

    assertEngineConfigNumber(config, field, 0, true);
  }
}

function validateEngineConfigVp9(config: Record<string, unknown>): void {
  if (
    typeof config.vp9CpuUsed !== "number" ||
    !Number.isInteger(config.vp9CpuUsed) ||
    config.vp9CpuUsed < -8 ||
    config.vp9CpuUsed > 8
  ) {
    throw new Error("Engine config vp9CpuUsed must be an integer in [-8, 8]");
  }
}

function validateEngineConfigRuntime(config: Record<string, unknown>): void {
  for (const field of BOOLEAN_ENGINE_CONFIG_FIELDS) {
    if (typeof config[field] !== "boolean")
      throw new Error(`Engine config ${field} must be a boolean`);
  }
  for (const field of POSITIVE_NUMBER_ENGINE_CONFIG_FIELDS) {
    assertEngineConfigNumber(config, field, 1, field === "frameDataUriCacheLimit");
  }
  assertEngineConfigNumber(config, "streamingEncodeMaxDurationSeconds", 0);
  assertEngineConfigNumber(config, "audioGain", 0);
}

function validateEngineConfigHdr(config: Record<string, unknown>): void {
  const { hdr } = config;
  if (
    hdr !== false &&
    (!isPlainObject(hdr) ||
      Object.keys(hdr).length !== 1 ||
      (hdr.transfer !== "hlg" && hdr.transfer !== "pq"))
  ) {
    throw new Error("Engine config hdr must be false or an hlg/pq transfer object");
  }

View on GitHub (pinned to c2996c8626)

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.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, debug: "true", disableGpu: 1 };

// after
const snap = { ...DEFAULT_CONFIG, debug: true, disableGpu: false };

Defensive patterns

Strategy: validation

Validate before calling

const BOOLEAN_FIELDS = ["disableGpu","enableBrowserPool","forceScreenshot","staticFrameDedup","useDrawElement","enableDrawElementWorkerEncode","lowMemoryMode","enablePageSideCompositing","enableChunkedEncode","enableStreamingEncode","hdrAutoDetect","verifyRuntime","debug"] as const;

for (const f of BOOLEAN_FIELDS) {
  if (typeof cfg[f] !== "boolean") throw new Error(`${f} must be a boolean`);
}

Type guard

function allBooleanFieldsPresent(config: Record<string, unknown>): boolean {
  return BOOLEAN_FIELDS.every((f) => typeof config[f] === "boolean");
}

Try / catch

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/must be a boolean/.test(String(e))) {
    const field = String(e).match(/Engine config (\w+) must be a boolean/)?.[1];
    if (field) (snapshot as any)[field] = Boolean((snapshot as any)[field]);
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/c6fb145ab33e2737. Report an issue: GitHub.