{"record":{"id":"8d9da99ebf058ca0","repo":"heygen-com/hyperframes","slug":"engine-config-field-must-be-a-non-empty-string","errorCode":null,"errorMessage":"Engine config ${field} must be a non-empty string","messagePattern":"Engine config (.+?) must be a non-empty string","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/engine/src/config.ts","lineNumber":491,"sourceCode":"function validateEngineConfigHdr(config: Record<string, unknown>): void {\n  const { hdr } = config;\n  if (\n    hdr !== false &&\n    (!isPlainObject(hdr) ||\n      Object.keys(hdr).length !== 1 ||\n      (hdr.transfer !== \"hlg\" && hdr.transfer !== \"pq\"))\n  ) {\n    throw new Error(\"Engine config hdr must be false or an hlg/pq transfer object\");\n  }\n}\n\nfunction validateOptionalEngineConfigFields(config: Record<string, unknown>): void {\n  for (const field of [\"chromePath\", \"runtimeManifestPath\", \"extractCacheDir\"] as const) {\n    if (\n      config[field] !== undefined &&\n      (typeof config[field] !== \"string\" || config[field].length === 0)\n    ) {\n      throw new Error(`Engine config ${field} must be a non-empty string`);\n    }\n  }\n  if (config.expectedChromiumMajor !== undefined) {\n    assertEngineConfigNumber(config, \"expectedChromiumMajor\", 1, true);\n  }\n  for (const field of [\n    \"pageSideCompositingAutoDisabled\",\n    \"forceScreenshotExplicitlyOptedOut\",\n    \"streamingEncodeAutoDisabledOnWin32Compound\",\n  ] as const) {\n    if (config[field] !== undefined && typeof config[field] !== \"boolean\") {\n      throw new Error(`Engine config ${field} must be a boolean`);\n    }\n  }\n}\n\n/**\n * Validate a complete EngineConfig crossing a JSON wire boundary.","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/engine/src/config.ts#L473-L509","documentation":"validateOptionalEngineConfigFields() checks the optional string fields chromePath, runtimeManifestPath, extractCacheDir: if present, they must be non-empty strings. Empty string, whitespace-only (not caught — only length 0 is), or a non-string type is rejected.","triggerScenarios":"validateEngineConfigSnapshot() receives chromePath: \"\" (set but blank), chromePath: null, or runtimeManifestPath set to a number. Undefined is allowed (the fields are optional); only a present-but-invalid value throws.","commonSituations":"Env var HF_CHROME_PATH unset resolving to empty string then assigned; a config builder defaulting absent optionals to \"\" instead of undefined; passing 0/null as a placeholder.","solutions":["If the path is unknown, omit the field entirely (or set to undefined) — do not use an empty string.","Otherwise set it to an absolute path string that exists.","In config builders, normalize `value || undefined` so falsy becomes absent rather than blank."],"exampleFix":"// before\nconst snap = { ...DEFAULT_CONFIG, chromePath: \"\" };\n\n// after\nconst snap = { ...DEFAULT_CONFIG, chromePath: process.env.HF_CHROME_PATH || undefined };","handlingStrategy":"validation","validationCode":"for (const f of [\"chromePath\",\"runtimeManifestPath\",\"extractCacheDir\"] as const) {\n  const v = cfg[f];\n  if (v !== undefined && (typeof v !== \"string\" || v.length === 0)) {\n    throw new Error(`${f} must be a non-empty string`);\n  }\n}","typeGuard":"function isOptionalNonEmptyString(value: unknown): boolean {\n  return value === undefined || (typeof value === \"string\" && value.length > 0);\n}","tryCatchPattern":"try { validateEngineConfigSnapshot(snapshot); }\ncatch (e) {\n  if (/must be a non-empty string/.test(String(e))) {\n    for (const f of [\"chromePath\",\"runtimeManifestPath\",\"extractCacheDir\"] as const) {\n      if (snapshot[f] === \"\") delete (snapshot as any)[f];\n    }\n    validateEngineConfigSnapshot(snapshot);\n  } else throw e;\n}","preventionTips":["Omit optional string fields rather than setting them to \"\".","Normalize `value || undefined` when sourcing from env/config builders.","When set, use an absolute path that exists."],"tags":["engine-config","validation","optional-fields","path"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}