{"record":{"id":"233009d9978d8e89","repo":"heygen-com/hyperframes","slug":"engine-config-snapshot-has-unknown-field-field","errorCode":null,"errorMessage":"Engine config snapshot has unknown field ${field}","messagePattern":"Engine config snapshot has unknown field (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":421,"sourceCode":"function assertEngineConfigEnum(\n  config: Record<string, unknown>,\n  field: string,\n  values: readonly unknown[],\n): void {\n  if (!values.includes(config[field])) throw new Error(`Engine config ${field} is invalid`);\n}\n\nfunction validateRequiredEngineConfigFields(config: Record<string, unknown>): void {\n  const requiredFields = Object.keys(DEFAULT_CONFIG);\n  for (const field of requiredFields) {\n    if (!Object.hasOwn(config, field)) {\n      throw new Error(`Engine config snapshot is missing required field ${field}`);\n    }\n  }\n  const allowedFields = new Set([...requiredFields, ...OPTIONAL_ENGINE_CONFIG_FIELDS]);\n  for (const field of Object.keys(config)) {\n    if (!allowedFields.has(field))\n      throw new Error(`Engine config snapshot has unknown field ${field}`);\n  }\n}\n\nfunction validateEngineConfigScalars(config: Record<string, unknown>): void {\n  for (const [field, values] of Object.entries(ENUM_ENGINE_CONFIG_FIELDS)) {\n    assertEngineConfigEnum(config, field, values);\n  }\n  assertEngineConfigNumber(config, \"jpegQuality\", 0);\n  if (typeof config.jpegQuality === \"number\" && config.jpegQuality > 100) {\n    throw new Error(\"Engine config jpegQuality must be <= 100\");\n  }\n}\n\nfunction validateEngineConfigParallelism(config: Record<string, unknown>): void {\n  if (\n    config.concurrency !== \"auto\" &&\n    (typeof config.concurrency !== \"number\" ||\n      !Number.isInteger(config.concurrency) ||","sourceCodeStart":403,"sourceCodeEnd":439,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L403-L439","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove or rename the unknown field named in the message to match the current EngineConfig schema.","Cross-check against OPTIONAL_ENGINE_CONFIG_FIELDS and DEFAULT_CONFIG keys in the installed engine version.","Regenerate the snapshot via resolveConfig() with only currently-supported overrides.","Clear any client-side cache of serialized snapshots after upgrading the engine."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, producerFps: 30 };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, fps: 30 };","handlingStrategy":"validation","validationCode":"import { DEFAULT_CONFIG } from \"@hyperframes/engine\";\n\nconst OPTIONAL = new Set([\"chromePath\",\"expectedChromiumMajor\",\"pageSideCompositingAutoDisabled\",\"forceScreenshotExplicitlyOptedOut\",\"streamingEncodeAutoDisabledOnWin32Compound\",\"runtimeManifestPath\",\"extractCacheDir\"]);\nconst ALLOWED = new Set([...Object.keys(DEFAULT_CONFIG), ...OPTIONAL]);\n\nfunction rejectUnknownFields(snapshot: Record<string, unknown>) {\n  for (const k of Object.keys(snapshot)) if (!ALLOWED.has(k)) throw new Error(`unknown field ${k}`);\n}","typeGuard":"function hasOnlyKnownEngineConfigFields(value: object): boolean {\n  return Object.keys(value).every((k) => ALLOWED.has(k));\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/unknown field/.test(String(e))) {\n    const field = String(e).match(/unknown field (\\S+)/)?.[1];\n    if (field) delete snapshot[field]; // drop stale field and retry\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["After engine upgrades, regenerate snapshots rather than reusing stale ones.","Source overrides from current documentation/types, not from memory.","Validate snapshots during development to surface schema drift early."],"tags":["engine-config","validation","unknown-field","schema","migration"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}