heygen-com/hyperframes · error · Error

Engine config snapshot has unknown 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.

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 is missing a `nodes` array.
• Chain file must be a JSON object.
• Engine config concurrency must be a positive integer or auto
• Engine config is invalid
• Engine config must be a boolean

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

Appendix: 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)