heygen-com/hyperframes · error · Error

Engine config snapshot is missing required field ${field}

Error message

Engine config snapshot is missing required field ${field}

What it means

validateRequiredEngineConfigFields() throws when a snapshot is missing any key present in DEFAULT_CONFIG. validateEngineConfigSnapshot() intentionally requires a *complete* resolved snapshot because a partial one would silently skip the orchestrator's resolveConfig() fallback — every DEFAULT_CONFIG field must be present.

Source

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

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

View on GitHub (pinned to c2996c8626)

Solutions

1. Build the snapshot with resolveConfig(overrides) so all DEFAULT_CONFIG fields are populated before validation/serialization.
2. If you must hand-build, spread DEFAULT_CONFIG first: `{ ...DEFAULT_CONFIG, ...yourOverrides }`.
3. On a version mismatch (new required field), regenerate the snapshot with the current engine version rather than patching the old one.

Example fix

// before
const snap = { fps: 30, quality: "standard" }; // missing ~30 required fields
validateEngineConfigSnapshot(snap);

// after
import { DEFAULT_CONFIG, resolveConfig } from "@hyperframes/engine";
const snap = resolveConfig({ fps: 30 }); // full + validated
validateEngineConfigSnapshot(snap);

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

function ensureCompleteSnapshot(partial: Record<string, unknown>) {
  for (const field of Object.keys(DEFAULT_CONFIG)) {
    if (!Object.hasOwn(partial, field)) {
      throw new Error(`snapshot missing required field ${field}; run resolveConfig() first`);
    }
  }
}

function isCompleteEngineConfig(value: unknown): boolean {
  if (typeof value !== "object" || value === null) return false;
  return Object.keys(DEFAULT_CONFIG).every((k) => Object.hasOwn(value, k));
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/missing required field/.test(String(e))) {
    const resolved = resolveConfig(snapshot); // re-resolve to fill defaults
    validateEngineConfigSnapshot(resolved);
  } else throw e;
}

When it happens

Trigger: Passing a hand-built or partial config object to validateEngineConfigSnapshot() without first running it through resolveConfig(). Common with serialized render requests assembled by a client that only sets the fields it cares about.

Common situations: A new engine release adds a required field to DEFAULT_CONFIG and an older client's serialized snapshot omits it; an external tool writes a render request from a template that drifted from the current schema; manually constructing a snapshot in tests without spreading DEFAULT_CONFIG.

Related errors

• Engine config ${field} must be a ${integer ? "finite integer
• Engine config snapshot must be a plain object
• Engine config ${field} must be a finite number > 0
• Engine config ${field} is invalid
• Engine config snapshot has unknown field ${field}

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