{"record":{"id":"84e1d948203d6217","repo":"heygen-com/hyperframes","slug":"engine-config-field-is-invalid","errorCode":null,"errorMessage":"Engine config ${field} is invalid","messagePattern":"Engine config (.+?) is invalid","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":408,"sourceCode":"    throw new Error(\n      `Engine config ${field} must be a ${integer ? \"finite integer\" : \"finite number\"} >= ${min}`,\n    );\n  }\n}\n\nfunction assertPositiveEngineConfigNumber(config: Record<string, unknown>, field: string): void {\n  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)) {","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L390-L426","documentation":"assertEngineConfigEnum() rejects a config field whose value is not in its allowed set. ENUM_ENGINE_CONFIG_FIELDS defines: fps ∈ {24,30,60}, quality ∈ {draft,standard,high}, format ∈ {jpeg,png}, browserGpuMode ∈ {software,hardware,auto}.","triggerScenarios":"validateEngineConfigSnapshot() receives fps: 25 or 60.0 (note: must be exactly 24/30/60, not a numeric-equivalent float that fails strict equality), quality/format/browserGpuMode with a typo or unsupported value (e.g. quality: \"ultra\", format: \"webp\", browserGpuMode: \"gpu\").","commonSituations":"Author wanting 25/50 fps (unsupported — only 24/30/60 wired through the timing system); typo in a serialized config; stale client sending a value from a renamed enum; passing fps as a string like \"30\".","solutions":["Set the field to one of the documented enum values exactly (fps number, others lowercase string).","For fps, choose 24/30/60 — other frame rates are not supported by the engine timing pipeline.","For browserGpuMode use `software`, `hardware`, or `auto`; for format use `jpeg` or `png`.","Re-resolve via resolveConfig() so the enum is sourced from DEFAULT_CONFIG defaults."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, fps: 25, browserGpuMode: \"gpu\" };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, fps: 30, browserGpuMode: \"hardware\" };","handlingStrategy":"type-guard","validationCode":"const FPS = [24, 30, 60] as const;\nconst QUALITY = [\"draft\", \"standard\", \"high\"] as const;\nconst FORMAT = [\"jpeg\", \"png\"] as const;\nconst GPU = [\"software\", \"hardware\", \"auto\"] as const;\n\nfunction assertEnum<T extends string | number>(field: string, value: unknown, allowed: readonly T[]): asserts value is T {\n  if (!allowed.includes(value as T)) throw new Error(`${field} must be one of ${allowed.join(\",\")}`);\n}\n\nassertEnum(\"fps\", cfg.fps, FPS);\nassertEnum(\"quality\", cfg.quality, QUALITY);\nassertEnum(\"format\", cfg.format, FORMAT);\nassertEnum(\"browserGpuMode\", cfg.browserGpuMode, GPU);","typeGuard":"function isEngineConfigEnum(value: unknown): boolean {\n  return (\n    (typeof value === \"number\" && [24,30,60].includes(value)) ||\n    (typeof value === \"string\" && [\"draft\",\"standard\",\"high\",\"jpeg\",\"png\",\"software\",\"hardware\",\"auto\"].includes(value))\n  );\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/Engine config .* is invalid/.test(String(e))) {\n    throw new Error(`Unsupported engine config value: ${e.message}`, { cause: e });\n  }\n  throw e;\n}","preventionTips":["Only use the documented enum values; do not invent frame rates or modes.","Prefer the `quality` enum over hand-tuning low-level fields.","Validate enums at the UI/config-authoring layer with a dropdown."],"tags":["engine-config","validation","enum","fps","gpu-mode"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}