heygen-com/hyperframes · error · Error

Engine config concurrency must be a positive integer or auto

Error message

Engine config concurrency must be a positive integer or auto

What it means

validateEngineConfigParallelism() requires `concurrency` to be either the literal string "auto" or a positive integer (>= 1). Floats, zero, negatives, non-integers, or other strings are rejected. coresPerWorker is validated separately by error 346.

Source

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

function validateEngineConfigScalars(config: Record<string, unknown>): void {
  for (const [field, values] of Object.entries(ENUM_ENGINE_CONFIG_FIELDS)) {
    assertEngineConfigEnum(config, field, values);
  }
  assertEngineConfigNumber(config, "jpegQuality", 0);
  if (typeof config.jpegQuality === "number" && config.jpegQuality > 100) {
    throw new Error("Engine config jpegQuality must be <= 100");
  }
}

function validateEngineConfigParallelism(config: Record<string, unknown>): void {
  if (
    config.concurrency !== "auto" &&
    (typeof config.concurrency !== "number" ||
      !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]");
  }
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Use concurrency: "auto" to let the engine pick, or an integer >= 1 (e.g. 1 to serialize, 4 for four workers).
2. Coerce UI/env input: `const c = raw === "auto" ? "auto" : Math.max(1, Math.floor(Number(raw)))`.
3. If you genuinely want no parallelism, set concurrency: 1, not 0.

Example fix

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

// after
const snap = { ...DEFAULT_CONFIG, concurrency: 1 };

function normalizeConcurrency(value: unknown): number | "auto" {
  if (value === "auto") return "auto";
  const n = typeof value === "number" ? value : Number(value);
  if (!Number.isInteger(n) || n < 1) throw new Error("concurrency must be \"auto\" or a positive integer");
  return n;
}
cfg.concurrency = normalizeConcurrency(cfg.concurrency);

function isValidConcurrency(value: unknown): boolean {
  return value === "auto" || (typeof value === "number" && Number.isInteger(value) && value >= 1);
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/concurrency must be/.test(String(e))) {
    snapshot.concurrency = "auto"; // safe default
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

When it happens

Trigger: validateEngineConfigSnapshot() receives concurrency: 0 (to serialize), concurrency: 2.5 (float), concurrency: "4" (string of a number), concurrency: -1, or a typo like "autos".

Common situations: Trying to force single-threaded rendering by setting concurrency to 0 (use 1 instead); passing a worker count from a UI as a string; a config tuned for a specific core count then run on a smaller host.

Related errors

• Engine config ${field} must be a ${integer ? "finite integer
• Engine config ${field} must be a finite number > 0
• Engine config ${field} is invalid
• Engine config snapshot is missing required field ${field}
• Engine config snapshot has unknown field ${field}

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