heygen-com/hyperframes · error · Error

Engine config ${field} is invalid

Error message

Engine config ${field} is invalid

What it means

assertEngineConfigEnum() rejects a config field whose value is not in its allowed set. ENUM_ENGINE_CONFIG_FIELDS defines: fps ∈ {24,30,60}, quality ∈ {draft,standard,high}, format ∈ {jpeg,png}, browserGpuMode ∈ {software,hardware,auto}.

Source

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

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

View on GitHub (pinned to c2996c8626)

Solutions

1. Set the field to one of the documented enum values exactly (fps number, others lowercase string).
2. For fps, choose 24/30/60 — other frame rates are not supported by the engine timing pipeline.
3. For browserGpuMode use `software`, `hardware`, or `auto`; for format use `jpeg` or `png`.
4. Re-resolve via resolveConfig() so the enum is sourced from DEFAULT_CONFIG defaults.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, fps: 25, browserGpuMode: "gpu" };

// after
const snap = { ...DEFAULT_CONFIG, fps: 30, browserGpuMode: "hardware" };

const FPS = [24, 30, 60] as const;
const QUALITY = ["draft", "standard", "high"] as const;
const FORMAT = ["jpeg", "png"] as const;
const GPU = ["software", "hardware", "auto"] as const;

function assertEnum<T extends string | number>(field: string, value: unknown, allowed: readonly T[]): asserts value is T {
  if (!allowed.includes(value as T)) throw new Error(`${field} must be one of ${allowed.join(",")}`);
}

assertEnum("fps", cfg.fps, FPS);
assertEnum("quality", cfg.quality, QUALITY);
assertEnum("format", cfg.format, FORMAT);
assertEnum("browserGpuMode", cfg.browserGpuMode, GPU);

function isEngineConfigEnum(value: unknown): boolean {
  return (
    (typeof value === "number" && [24,30,60].includes(value)) ||
    (typeof value === "string" && ["draft","standard","high","jpeg","png","software","hardware","auto"].includes(value))
  );
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/Engine config .* is invalid/.test(String(e))) {
    throw new Error(`Unsupported engine config value: ${e.message}`, { cause: e });
  }
  throw e;
}

When it happens

Trigger: validateEngineConfigSnapshot() receives fps: 25 or 60.0 (note: must be exactly 24/30/60, not a numeric-equivalent float that fails strict equality), quality/format/browserGpuMode with a typo or unsupported value (e.g. quality: "ultra", format: "webp", browserGpuMode: "gpu").

Common situations: Author wanting 25/50 fps (unsupported — only 24/30/60 wired through the timing system); typo in a serialized config; stale client sending a value from a renamed enum; passing fps as a string like "30".

Related errors

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

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