heygen-com/hyperframes · error · Error

Engine config jpegQuality must be <= 100

Error message

Engine config jpegQuality must be <= 100

What it means

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].

Source

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

  for (const field of requiredFields) {
    if (!Object.hasOwn(config, field)) {
      throw new Error(`Engine config snapshot is missing required field ${field}`);
    }
  }
  const allowedFields = new Set([...requiredFields, ...OPTIONAL_ENGINE_CONFIG_FIELDS]);
  for (const field of Object.keys(config)) {
    if (!allowedFields.has(field))
      throw new Error(`Engine config snapshot has unknown field ${field}`);
  }
}

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);
  }
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Set jpegQuality to an integer in [0,100] (default 80; use ~90–95 for high quality).
2. If you passed a 0–1 float, multiply by 100.
3. Prefer using the `quality` enum (draft/standard/high) which maps to sensible jpegQuality values.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, jpegQuality: 1000 };

// after
const snap = { ...DEFAULT_CONFIG, jpegQuality: 90 };

if (typeof cfg.jpegQuality !== "number" || cfg.jpegQuality < 0 || cfg.jpegQuality > 100) {
  throw new Error("jpegQuality must be a number in [0,100]");
}

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

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/jpegQuality must be <= 100/.test(String(e))) {
    snapshot.jpegQuality = Math.min(100, Math.max(0, snapshot.jpegQuality));
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Engine config vp9CpuUsed must be an integer in [-8, 8]
• 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/75463e02d94d3940. Report an issue: GitHub.