{"record":{"id":"75463e02d94d3940","repo":"heygen-com/hyperframes","slug":"engine-config-jpegquality-must-be-100","errorCode":null,"errorMessage":"Engine config jpegQuality must be <= 100","messagePattern":"Engine config jpegQuality must be <= 100","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":431,"sourceCode":"  for (const field of requiredFields) {\n    if (!Object.hasOwn(config, field)) {\n      throw new Error(`Engine config snapshot is missing required field ${field}`);\n    }\n  }\n  const allowedFields = new Set([...requiredFields, ...OPTIONAL_ENGINE_CONFIG_FIELDS]);\n  for (const field of Object.keys(config)) {\n    if (!allowedFields.has(field))\n      throw new Error(`Engine config snapshot has unknown field ${field}`);\n  }\n}\n\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","sourceCodeStart":413,"sourceCodeEnd":449,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L413-L449","documentation":"validateEngineConfigScalars() enforces an upper bound on jpegQuality: after assertEngineConfigNumber confirms it is a finite number >= 0, this check rejects values > 100. jpegQuality is the JPEG encode quality passed to Chrome's capture and must be in [0,100].","triggerScenarios":"validateEngineConfigSnapshot() receives jpegQuality > 100 — e.g. 101, 1000, or a percentage like 100 misentered as 1000. Values below 0 are caught earlier by error 345.","commonSituations":"Confusing jpegQuality (0–100) with a 0–1 ratio; copy-pasting a CRF value from an ffmpeg command (which can exceed 100 in some contexts); a UI slider that let the value exceed 100; defaulting to 100 'for max quality' then typo to 1000.","solutions":["Set jpegQuality to an integer in [0,100] (default 80; use ~90–95 for high quality).","If you passed a 0–1 float, multiply by 100.","Prefer using the `quality` enum (draft/standard/high) which maps to sensible jpegQuality values."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, jpegQuality: 1000 };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, jpegQuality: 90 };","handlingStrategy":"validation","validationCode":"if (typeof cfg.jpegQuality !== \"number\" || cfg.jpegQuality < 0 || cfg.jpegQuality > 100) {\n  throw new Error(\"jpegQuality must be a number in [0,100]\");\n}","typeGuard":"function isValidJpegQuality(value: unknown): boolean {\n  return typeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= 100;\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/jpegQuality must be <= 100/.test(String(e))) {\n    snapshot.jpegQuality = Math.min(100, Math.max(0, snapshot.jpegQuality));\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Remember jpegQuality is 0–100, not 0–1 and not a CRF.","Prefer the `quality` enum (draft/standard/high) which maps to safe jpegQuality values.","Clamp UI slider input to [0,100]."],"tags":["engine-config","validation","jpeg-quality","range"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}