heygen-com/hyperframes · error · Error

Engine config vp9CpuUsed must be an integer in [-8, 8]

Error message

Engine config vp9CpuUsed must be an integer in [-8, 8]

What it means

validateEngineConfigVp9() requires vp9CpuUsed to be an integer in the closed range [-8, 8] — the documented libvpx `-cpu-used` quality/speed bracket. Non-integers, values outside that range, or non-numbers are rejected.

Source

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

      !Number.isInteger(config.concurrency) ||
      config.concurrency < 1)
  ) {
    throw new Error("Engine config concurrency must be a positive integer or auto");
  }
  assertPositiveEngineConfigNumber(config, "coresPerWorker");
  for (const field of ["minParallelFrames", "largeRenderThreshold"] as const) {
    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 (

View on GitHub (pinned to c2996c8626)

Solutions

1. Set vp9CpuUsed to an integer in [-8, 8] (higher = faster/lower quality; default is sane for most renders).
2. If unsure, omit it and let resolveConfig() apply DEFAULT_VP9_CPU_USED.
3. Use normalizeVp9CpuUsed() (exported from the engine's vp9Options module) to clamp an external value before snapshotting.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, vp9CpuUsed: 16 };

// after
const snap = { ...DEFAULT_CONFIG, vp9CpuUsed: 4 };

function normalizeVp9CpuUsed(value: unknown): number {
  const n = typeof value === "number" ? value : Number(value);
  if (!Number.isInteger(n) || n < -8 || n > 8) throw new Error("vp9CpuUsed must be an integer in [-8,8]");
  return n;
}
cfg.vp9CpuUsed = normalizeVp9CpuUsed(cfg.vp9CpuUsed);

function isValidVp9CpuUsed(value: unknown): boolean {
  return typeof value === "number" && Number.isInteger(value) && value >= -8 && value <= 8;
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/vp9CpuUsed/.test(String(e))) {
    snapshot.vp9CpuUsed = DEFAULT_CONFIG.vp9CpuUsed;
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

When it happens

Trigger: validateEngineConfigSnapshot() receives vp9CpuUsed outside [-8,8] (e.g. 9 or -10), a float (4.5), or a non-number. DEFAULT_VP9_CPU_USED is the safe default; resolveConfig() also normalizes via normalizeVp9CpuUsed, so this usually only fires for raw snapshots.

Common situations: Confusing vp9CpuUsed with jpegQuality scale; passing a CRF or bitrate value into the wrong field; an older config that used a different range; typo negative bound.

Related errors

• Engine config jpegQuality must be <= 100
• A color curve requires at least two points
• Curve LUT size must be at least 2
• Color curve inputs must be strictly increasing
• Curve output bounds must be finite and increasing

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