heygen-com/hyperframes · error · Error

Engine config ${field} must be a non-empty string

Error message

Engine config ${field} must be a non-empty string

What it means

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.

Source

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

function validateEngineConfigHdr(config: Record<string, unknown>): void {
  const { hdr } = config;
  if (
    hdr !== false &&
    (!isPlainObject(hdr) ||
      Object.keys(hdr).length !== 1 ||
      (hdr.transfer !== "hlg" && hdr.transfer !== "pq"))
  ) {
    throw new Error("Engine config hdr must be false or an hlg/pq transfer object");
  }
}

function validateOptionalEngineConfigFields(config: Record<string, unknown>): void {
  for (const field of ["chromePath", "runtimeManifestPath", "extractCacheDir"] as const) {
    if (
      config[field] !== undefined &&
      (typeof config[field] !== "string" || config[field].length === 0)
    ) {
      throw new Error(`Engine config ${field} must be a non-empty string`);
    }
  }
  if (config.expectedChromiumMajor !== undefined) {
    assertEngineConfigNumber(config, "expectedChromiumMajor", 1, true);
  }
  for (const field of [
    "pageSideCompositingAutoDisabled",
    "forceScreenshotExplicitlyOptedOut",
    "streamingEncodeAutoDisabledOnWin32Compound",
  ] as const) {
    if (config[field] !== undefined && typeof config[field] !== "boolean") {
      throw new Error(`Engine config ${field} must be a boolean`);
    }
  }
}

/**
 * Validate a complete EngineConfig crossing a JSON wire boundary.

View on GitHub (pinned to c2996c8626)

Solutions

1. If the path is unknown, omit the field entirely (or set to undefined) — do not use an empty string.
2. Otherwise set it to an absolute path string that exists.
3. In config builders, normalize `value || undefined` so falsy becomes absent rather than blank.

Example fix

// before
const snap = { ...DEFAULT_CONFIG, chromePath: "" };

// after
const snap = { ...DEFAULT_CONFIG, chromePath: process.env.HF_CHROME_PATH || undefined };

for (const f of ["chromePath","runtimeManifestPath","extractCacheDir"] as const) {
  const v = cfg[f];
  if (v !== undefined && (typeof v !== "string" || v.length === 0)) {
    throw new Error(`${f} must be a non-empty string`);
  }
}

function isOptionalNonEmptyString(value: unknown): boolean {
  return value === undefined || (typeof value === "string" && value.length > 0);
}

try { validateEngineConfigSnapshot(snapshot); }
catch (e) {
  if (/must be a non-empty string/.test(String(e))) {
    for (const f of ["chromePath","runtimeManifestPath","extractCacheDir"] as const) {
      if (snapshot[f] === "") delete (snapshot as any)[f];
    }
    validateEngineConfigSnapshot(snapshot);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

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