{"record":{"id":"56f83a23385e86d7","repo":"heygen-com/hyperframes","slug":"engine-config-concurrency-must-be-a-positive-integ","errorCode":null,"errorMessage":"Engine config concurrency must be a positive integer or auto","messagePattern":"Engine config concurrency must be a positive integer or auto","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":442,"sourceCode":"\nfunction validateEngineConfigScalars(config: Record<string, unknown>): void {\n  for (const [field, values] of Object.entries(ENUM_ENGINE_CONFIG_FIELDS)) {\n    assertEngineConfigEnum(config, field, values);\n  }\n  assertEngineConfigNumber(config, \"jpegQuality\", 0);\n  if (typeof config.jpegQuality === \"number\" && config.jpegQuality > 100) {\n    throw new Error(\"Engine config jpegQuality must be <= 100\");\n  }\n}\n\nfunction validateEngineConfigParallelism(config: Record<string, unknown>): void {\n  if (\n    config.concurrency !== \"auto\" &&\n    (typeof config.concurrency !== \"number\" ||\n      !Number.isInteger(config.concurrency) ||\n      config.concurrency < 1)\n  ) {\n    throw new Error(\"Engine config concurrency must be a positive integer or auto\");\n  }\n  assertPositiveEngineConfigNumber(config, \"coresPerWorker\");\n  for (const field of [\"minParallelFrames\", \"largeRenderThreshold\"] as const) {\n    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","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L424-L460","documentation":"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.","triggerScenarios":"validateEngineConfigSnapshot() receives concurrency: 0 (to serialize), concurrency: 2.5 (float), concurrency: \"4\" (string of a number), concurrency: -1, or a typo like \"autos\".","commonSituations":"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.","solutions":["Use concurrency: \"auto\" to let the engine pick, or an integer >= 1 (e.g. 1 to serialize, 4 for four workers).","Coerce UI/env input: `const c = raw === \"auto\" ? \"auto\" : Math.max(1, Math.floor(Number(raw)))`.","If you genuinely want no parallelism, set concurrency: 1, not 0."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, concurrency: 0 };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, concurrency: 1 };","handlingStrategy":"validation","validationCode":"function normalizeConcurrency(value: unknown): number | \"auto\" {\n  if (value === \"auto\") return \"auto\";\n  const n = typeof value === \"number\" ? value : Number(value);\n  if (!Number.isInteger(n) || n < 1) throw new Error(\"concurrency must be \\\"auto\\\" or a positive integer\");\n  return n;\n}\ncfg.concurrency = normalizeConcurrency(cfg.concurrency);","typeGuard":"function isValidConcurrency(value: unknown): boolean {\n  return value === \"auto\" || (typeof value === \"number\" && Number.isInteger(value) && value >= 1);\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/concurrency must be/.test(String(e))) {\n    snapshot.concurrency = \"auto\"; // safe default\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Use \"auto\" when in doubt; use an integer >= 1 to pin workers.","Coerce UI/env input to number-or-\"auto\" before snapshotting.","Never use 0 to disable parallelism — use 1."],"tags":["engine-config","validation","concurrency","parallelism"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}