heygen-com/hyperframes · error · Error

--launch-args-json must contain a JSON string array: ${resol

Error message

--launch-args-json must contain a JSON string array: ${resolved}

What it means

readLaunchArgs reads the JSON file at the given path, parses it, and validates that the result is an array where every element is a string. If the parsed value is not an array, or any element is not a string, it throws with the resolved file path. The file must contain a top-level JSON string array like ["--no-sandbox", "--disable-gpu"].

Source

Thrown at packages/aws-lambda/scripts/probe-beginframe.ts:104

    if (arg.startsWith("--launch-args-json=")) {
      const value = arg.slice("--launch-args-json=".length);
      if (!value) throw new Error("--launch-args-json requires a path");
      launchArgs = readLaunchArgs(value);
      continue;
    }
    throw new Error(`Unknown argument: ${arg}`);
  }
  return {
    ...(executablePath ? { executablePath } : {}),
    ...(launchArgs ? { launchArgs } : {}),
  };
}

function readLaunchArgs(path: string): string[] {
  const resolved = resolve(path);
  const value: unknown = JSON.parse(readFileSync(resolved, "utf-8"));
  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
    throw new Error(`--launch-args-json must contain a JSON string array: ${resolved}`);
  }
  return value;
}

async function awaitBeforeDeadline<T>(
  operation: Promise<T>,
  deadline: number,
  label: string,
): Promise<T> {
  const remainingMs = deadline - Date.now();
  if (remainingMs <= 0) throw new Error(`BeginFrame probe timeout before ${label}`);
  let timeout: ReturnType<typeof setTimeout> | undefined;
  try {
    return await Promise.race([
      operation,
      new Promise<never>((_, reject) => {
        timeout = setTimeout(
          () => reject(new Error(`BeginFrame probe timeout during ${label}`)),

View on GitHub (pinned to c2996c8626)

Solutions

1. Ensure the file contains only a JSON array of strings: ["--no-sandbox", "--disable-gpu"].
2. Validate the file before running: node -e "const v=JSON.parse(require('fs').readFileSync('args.json','utf8')); if(!Array.isArray(v)||!v.every(x=>typeof x==='string')) throw new Error('invalid')".
3. Remove any object wrappers or non-string elements from the array.

Example fix

// before (launch-args.json)
--no-sandbox

// after (launch-args.json)
["--no-sandbox"]

import { readFileSync } from "node:fs";
function validateLaunchArgsFile(path: string): void {
  const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
  if (!isStringArray(raw)) {
    throw new Error(`${path} must contain a JSON string array`);
  }
}

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((item) => typeof item === "string");
}

try {
  validateLaunchArgsFile(resolved);
} catch (e) {
  if (e instanceof Error && e.message.includes("must contain a JSON string array")) {
    console.error(`Launch args file is invalid. Expected: ["--flag1", "--flag2"]`);
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: The JSON file exists and parses successfully but its content is not string[] — it is a bare string, an object, a number, or an array containing non-string elements.

Common situations: Saving a bare flag string instead of an array ('--no-sandbox' instead of ["--no-sandbox"]); wrapping in an object ({"args": [...]}); including non-string values like numbers or booleans in the array.

Related errors

• --executable-path requires a path
• --launch-args-json requires a path
• Unknown argument: ${arg}
• --source must be 'sparticuz' or 'chrome-headless-shell' (got
• Unknown flag: ${arg}

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