heygen-com/hyperframes · error · Error

Engine config snapshot has unknown field ${field}

Error message

Engine config snapshot has unknown field ${field}

What it means

validateRequiredEngineConfigFields() throws when a snapshot contains a key that is neither in DEFAULT_CONFIG nor in OPTIONAL_ENGINE_CONFIG_FIELDS (chromePath, expectedChromiumMajor, pageSideCompositingAutoDisabled, forceScreenshotExplicitlyOptedOut, streamingEncodeAutoDisabledOnWin32Compound, runtimeManifestPath, extractCacheDir). This guards against typos and stale fields silently being ignored.

Source

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

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)) {
    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) ||

View on GitHub (pinned to c2996c8626)

Solutions

1. Remove or rename the unknown field named in the message to match the current EngineConfig schema.
2. Cross-check against OPTIONAL_ENGINE_CONFIG_FIELDS and DEFAULT_CONFIG keys in the installed engine version.
3. Regenerate the snapshot via resolveConfig() with only currently-supported overrides.
4. Clear any client-side cache of serialized snapshots after upgrading the engine.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, producerFps: 30 };

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

import { DEFAULT_CONFIG } from "@hyperframes/engine";

const OPTIONAL = new Set(["chromePath","expectedChromiumMajor","pageSideCompositingAutoDisabled","forceScreenshotExplicitlyOptedOut","streamingEncodeAutoDisabledOnWin32Compound","runtimeManifestPath","extractCacheDir"]);
const ALLOWED = new Set([...Object.keys(DEFAULT_CONFIG), ...OPTIONAL]);

function rejectUnknownFields(snapshot: Record<string, unknown>) {
  for (const k of Object.keys(snapshot)) if (!ALLOWED.has(k)) throw new Error(`unknown field ${k}`);
}

function hasOnlyKnownEngineConfigFields(value: object): boolean {
  return Object.keys(value).every((k) => ALLOWED.has(k));
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/unknown field/.test(String(e))) {
    const field = String(e).match(/unknown field (\S+)/)?.[1];
    if (field) delete snapshot[field]; // drop stale field and retry
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

When it happens

Trigger: A serialized snapshot includes a renamed/removed field (e.g. an old `producerFps` after migration to `fps`), a typo (`browerGpuMode`), or an internal-only field that was never part of the public schema.

Common situations: Upgrading the engine after a field was renamed/removed; external tooling writing fields from documentation that is out of date; copy-pasting config between projects of different engine versions; a stale snapshot cached client-side from a previous major.

Related errors

• Chain file must be a JSON object.
• Chain file is missing a `nodes` array.
• Node ${i} is not an object.
• Engine config ${field} must be a ${integer ? "finite integer
• Engine config ${field} must be a finite number > 0

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