What causes "Engine config ${field} must be a finite number > 0" in heygen-com/hyperframes?

Set coresPerWorker to a positive finite number (default 2.5; integers not required).

heygen-com/hyperframes · error · Error

Engine config ${field} must be a finite number > 0

Error message

Engine config ${field} must be a finite number > 0

What it means

assertPositiveEngineConfigNumber() requires a strictly positive finite number. It is applied to `coresPerWorker` only — the CPU cores allocated per render worker, whose DEFAULT_CONFIG value is 2.5 (a float is allowed, but the value must be > 0).

Source

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

  integer = false,
): void {
  const value = config[field];
  if (
    typeof value !== "number" ||
    !Number.isFinite(value) ||
    value < min ||
    (integer && !Number.isInteger(value))
  ) {
    throw new Error(
      `Engine config ${field} must be a ${integer ? "finite integer" : "finite number"} >= ${min}`,
    );
  }
}

function assertPositiveEngineConfigNumber(config: Record<string, unknown>, field: string): void {
  const value = config[field];
  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
    throw new Error(`Engine config ${field} must be a finite number > 0`);
  }
}

function assertEngineConfigEnum(
  config: Record<string, unknown>,
  field: string,
  values: readonly unknown[],
): void {
  if (!values.includes(config[field])) throw new Error(`Engine config ${field} is invalid`);
}

function validateRequiredEngineConfigFields(config: Record<string, unknown>): void {
  const requiredFields = Object.keys(DEFAULT_CONFIG);
  for (const field of requiredFields) {
    if (!Object.hasOwn(config, field)) {
      throw new Error(`Engine config snapshot is missing required field ${field}`);
    }
  }

View on GitHub (pinned to c2996c8626)

Solutions

Set coresPerWorker to a positive finite number (default 2.5; integers not required).
If the goal is fewer workers, tune `concurrency` instead — leave coresPerWorker > 0.
Run the snapshot through resolveConfig() so the default is filled when the field is omitted.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, coresPerWorker: 0 };

// after
const snap = { ...DEFAULT_CONFIG, coresPerWorker: 2.5 };

Defensive patterns

Strategy: validation

Validate before calling

if (typeof cfg.coresPerWorker !== "number" || !Number.isFinite(cfg.coresPerWorker) || cfg.coresPerWorker <= 0) {
  throw new Error("coresPerWorker must be a finite number > 0");
}

Type guard

function isValidCoresPerWorker(value: unknown): boolean {
  return typeof value === "number" && Number.isFinite(value) && value > 0;
}

Try / catch

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/coresPerWorker/.test(String(e))) {
    snapshot.coresPerWorker = DEFAULT_CONFIG.coresPerWorker; // fall back to default
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

Prevention

Never set coresPerWorker to 0; tune concurrency to control worker count.
Source coresPerWorker from DEFAULT_CONFIG unless you have a measured reason to override.

When it happens

Trigger: validateEngineConfigSnapshot() receives a snapshot with coresPerWorker set to 0, a negative number, NaN/Infinity, or a non-number (string/undefined/null). Because coresPerWorker controls worker sizing, zero or negative would under-allocate or break worker count math.

Common situations: Overriding coresPerWorker to 0 to "disable" workers (use concurrency instead); env var misparsed; a config editor defaulting an unset field to 0; stale snapshot from an older schema that omitted the field then set it to a placeholder.

Related errors

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