{"record":{"id":"4817235f934866b4","repo":"heygen-com/hyperframes","slug":"engine-config-snapshot-is-missing-required-field","errorCode":null,"errorMessage":"Engine config snapshot is missing required field ${field}","messagePattern":"Engine config snapshot is missing required field (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":415,"sourceCode":"  const value = config[field];\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new Error(`Engine config ${field} must be a finite number > 0`);\n  }\n}\n\nfunction 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}","sourceCodeStart":397,"sourceCodeEnd":433,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L397-L433","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Build the snapshot with resolveConfig(overrides) so all DEFAULT_CONFIG fields are populated before validation/serialization.","If you must hand-build, spread DEFAULT_CONFIG first: `{ ...DEFAULT_CONFIG, ...yourOverrides }`.","On a version mismatch (new required field), regenerate the snapshot with the current engine version rather than patching the old one."],"exampleFix":"// before\nconst snap = { fps: 30, quality: \"standard\" }; // missing ~30 required fields\nvalidateEngineConfigSnapshot(snap);\n\n// after\nimport { DEFAULT_CONFIG, resolveConfig } from \"@hyperframes/engine\";\nconst snap = resolveConfig({ fps: 30 }); // full + validated\nvalidateEngineConfigSnapshot(snap);","handlingStrategy":"validation","validationCode":"import { DEFAULT_CONFIG } from \"@hyperframes/engine\";\n\nfunction ensureCompleteSnapshot(partial: Record<string, unknown>) {\n  for (const field of Object.keys(DEFAULT_CONFIG)) {\n    if (!Object.hasOwn(partial, field)) {\n      throw new Error(`snapshot missing required field ${field}; run resolveConfig() first`);\n    }\n  }\n}","typeGuard":"function isCompleteEngineConfig(value: unknown): boolean {\n  if (typeof value !== \"object\" || value === null) return false;\n  return Object.keys(DEFAULT_CONFIG).every((k) => Object.hasOwn(value, k));\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/missing required field/.test(String(e))) {\n    const resolved = resolveConfig(snapshot); // re-resolve to fill defaults\n    validateEngineConfigSnapshot(resolved);\n  } else throw e;\n}","preventionTips":["Always build snapshots with resolveConfig(overrides) before serializing.","Spread DEFAULT_CONFIG when constructing snapshots manually: `{ ...DEFAULT_CONFIG, ...overrides }`.","Regenerate cached client snapshots after every engine version bump."],"tags":["engine-config","validation","required-fields","snapshot"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}