{"record":{"id":"bfc9c29846bf7e9c","repo":"heygen-com/hyperframes","slug":"launch-args-json-must-contain-a-json-string-arra","errorCode":null,"errorMessage":"--launch-args-json must contain a JSON string array: ${resolved}","messagePattern":"--launch-args-json must contain a JSON string array: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/aws-lambda/scripts/probe-beginframe.ts","lineNumber":104,"sourceCode":"    if (arg.startsWith(\"--launch-args-json=\")) {\n      const value = arg.slice(\"--launch-args-json=\".length);\n      if (!value) throw new Error(\"--launch-args-json requires a path\");\n      launchArgs = readLaunchArgs(value);\n      continue;\n    }\n    throw new Error(`Unknown argument: ${arg}`);\n  }\n  return {\n    ...(executablePath ? { executablePath } : {}),\n    ...(launchArgs ? { launchArgs } : {}),\n  };\n}\n\nfunction readLaunchArgs(path: string): string[] {\n  const resolved = resolve(path);\n  const value: unknown = JSON.parse(readFileSync(resolved, \"utf-8\"));\n  if (!Array.isArray(value) || !value.every((item) => typeof item === \"string\")) {\n    throw new Error(`--launch-args-json must contain a JSON string array: ${resolved}`);\n  }\n  return value;\n}\n\nasync function awaitBeforeDeadline<T>(\n  operation: Promise<T>,\n  deadline: number,\n  label: string,\n): Promise<T> {\n  const remainingMs = deadline - Date.now();\n  if (remainingMs <= 0) throw new Error(`BeginFrame probe timeout before ${label}`);\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n  try {\n    return await Promise.race([\n      operation,\n      new Promise<never>((_, reject) => {\n        timeout = setTimeout(\n          () => reject(new Error(`BeginFrame probe timeout during ${label}`)),","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/aws-lambda/scripts/probe-beginframe.ts#L86-L122","documentation":"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\"].","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the file contains only a JSON array of strings: [\"--no-sandbox\", \"--disable-gpu\"].","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')\".","Remove any object wrappers or non-string elements from the array."],"exampleFix":"// before (launch-args.json)\n--no-sandbox\n\n// after (launch-args.json)\n[\"--no-sandbox\"]","handlingStrategy":"type-guard","validationCode":"import { readFileSync } from \"node:fs\";\nfunction validateLaunchArgsFile(path: string): void {\n  const raw: unknown = JSON.parse(readFileSync(path, \"utf-8\"));\n  if (!isStringArray(raw)) {\n    throw new Error(`${path} must contain a JSON string array`);\n  }\n}","typeGuard":"function isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}","tryCatchPattern":"try {\n  validateLaunchArgsFile(resolved);\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"must contain a JSON string array\")) {\n    console.error(`Launch args file is invalid. Expected: [\"--flag1\", \"--flag2\"]`);\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Always write launch-args JSON as a top-level array of strings.","Validate the JSON file format in a pre-commit hook or CI step.","Do not wrap args in an object or include non-string values."],"tags":["cli","json-validation","argument-validation","probe"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}