{"record":{"id":"12448f9279563361","repo":"heygen-com/hyperframes","slug":"batch-must-be-a-json-array-of-objects-or-an-obj","errorCode":null,"errorMessage":"--batch must be a JSON array of objects, or an object with a \"rows\" array.","messagePattern":"--batch must be a JSON array of objects, or an object with a \"rows\" array\\.","errorType":"validation","errorClass":"BatchRenderInputError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/batchRender.ts","lineNumber":104,"sourceCode":"\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction parseJson(raw: string, source: string): unknown {\n  try {\n    return JSON.parse(raw);\n  } catch (error: unknown) {\n    throw new BatchRenderInputError(\"Invalid JSON in --batch\", `${source}: ${errorMessage(error)}`);\n  }\n}\n\nexport function parseBatchRows(raw: string, source: string): Record<string, unknown>[] {\n  const parsed = parseJson(raw, source);\n  const rows = Array.isArray(parsed) ? parsed : isRecord(parsed) ? parsed.rows : undefined;\n\n  if (!Array.isArray(rows)) {\n    throw new BatchRenderInputError(\n      \"Invalid batch payload\",\n      '--batch must be a JSON array of objects, or an object with a \"rows\" array.',\n    );\n  }\n  if (rows.length === 0) {\n    throw new BatchRenderInputError(\"Empty batch\", `${source} contains zero rows.`);\n  }\n\n  return rows.map((row, index) => {\n    if (!isRecord(row)) {\n      throw new BatchRenderInputError(\n        \"Invalid batch row\",\n        `Row ${index} must be a JSON object of variable values.`,\n      );\n    }\n    return row;\n  });\n}","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/batchRender.ts#L86-L122","documentation":"BatchRenderInputError with title 'Invalid batch payload', thrown by parseBatchRows when the parsed JSON is neither an array nor an object exposing a 'rows' array. The accepted shapes are exactly: a JSON array of row objects, or { rows: [...] }. Anything else (a bare object without rows, a number, a string) trips this check before any row-level validation.","triggerScenarios":"Passing --batch '{\"color\":\"red\"}' (a single object with no rows array), '--batch \"42\"', or '--batch \"{\\\"rows\\\":123}\"' (rows present but not an array).","commonSituations":"Confusing the single-row --vars payload with the multi-row --batch shape; wrapping the array under a different key (e.g. 'data'); passing a top-level object whose rows field is null.","solutions":["Provide a JSON array of row objects: `[{...},{...}]`.","Or wrap in { rows: [...] } if you prefer the envelope shape.","Ensure 'rows' (if used) is actually an array, not a single object."],"exampleFix":"# before: bare object, no rows array\nhyperframes render --batch '{\"color\":\"red\"}'\n\n# after: array of row objects\nhyperframes render --batch '[{\"color\":\"red\"},{\"color\":\"blue\"}]'","handlingStrategy":"type-guard","validationCode":"function normalizeRows(parsed: unknown): unknown[] {\n  if (Array.isArray(parsed)) return parsed;\n  if (parsed && typeof parsed === 'object' && Array.isArray((parsed as any).rows)) {\n    return (parsed as any).rows;\n  }\n  throw new Error('--batch must be a JSON array of objects or { rows: [...] }');\n}","typeGuard":"function isRowsEnvelope(v: unknown): v is { rows: unknown[] } {\n  return !!v && typeof v === 'object' && !Array.isArray(v) && Array.isArray((v as any).rows);\n}","tryCatchPattern":"try {\n  parseBatchRows(raw, source);\n} catch (err) {\n  if (err instanceof BatchRenderInputError && err.title === 'Invalid batch payload') {\n    // re-wrap as [...] or { rows: [...] }\n  }\n}","preventionTips":["Use the array-of-objects form as the default; it is the least surprising.","If you prefer the envelope, always use the key 'rows'.","Do not conflate --batch (multi-row) with --vars (single object)."],"tags":["cli","validation","json","batch"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}