What causes "${source}: ${errorMessage(error)}" in heygen-com/hyperframes?

Validate the payload: `echo ' ' | jq .` or `jq . batch.json`.

heygen-com/hyperframes · error · BatchRenderInputError

${source}: ${errorMessage(error)}

Error message

${source}: ${errorMessage(error)}

What it means

BatchRenderInputError with title 'Invalid JSON in --batch', thrown by parseJson when JSON.parse(raw) fails on the --batch payload (inline string or file contents). The message includes the source label and the underlying parse error so the user can locate the bad JSON. It is the batch equivalent of the single-row invalid-vars error.

Source

Thrown at packages/cli/src/commands/batchRender.ts:95

  prepared: PreparedBatchRender;
  concurrency: number;
  failFast: boolean;
  quiet: boolean;
  json: boolean;
  renderOne: (row: PreparedBatchRow) => Promise<BatchRenderResult>;
}

const PLACEHOLDER_RE = /\{([A-Za-z0-9_.-]+)\}/g;

function isRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === "object" && !Array.isArray(value);
}

function parseJson(raw: string, source: string): unknown {
  try {
    return JSON.parse(raw);
  } catch (error: unknown) {
    throw new BatchRenderInputError("Invalid JSON in --batch", `${source}: ${errorMessage(error)}`);
  }
}

export function parseBatchRows(raw: string, source: string): Record<string, unknown>[] {
  const parsed = parseJson(raw, source);
  const rows = Array.isArray(parsed) ? parsed : isRecord(parsed) ? parsed.rows : undefined;

  if (!Array.isArray(rows)) {
    throw new BatchRenderInputError(
      "Invalid batch payload",
      '--batch must be a JSON array of objects, or an object with a "rows" array.',
    );
  }
  if (rows.length === 0) {
    throw new BatchRenderInputError("Empty batch", `${source} contains zero rows.`);
  }

  return rows.map((row, index) => {

View on GitHub (pinned to c2996c8626)

Solutions

Validate the payload: `echo '<json>' | jq .` or `jq . batch.json`.
If loading from a file, ensure the file contains only JSON (no trailing log lines, no BOM).
Use strict JSON (double quotes, no trailing commas, no comments).

Example fix

# before: trailing comma, single quotes
hyperframes render --batch '[{ "out": "a.mp4" }, ]'

# after: strict JSON
hyperframes render --batch '[{"out":"a.mp4"}]'

Defensive patterns

Strategy: validation

Validate before calling

function assertValidBatchJson(raw: string, source: string) {
  try { JSON.parse(raw); }
  catch (e) { throw new Error(`${source} is not valid JSON: ${(e as Error).message}`); }
}

Try / catch

try {
  parseBatchRows(raw, source);
} catch (err) {
  if (err instanceof BatchRenderInputError && err.title === 'Invalid JSON in --batch') {
    // show jq-validated corrected payload
  }
}

Prevention

Validate with `jq .` before passing --batch.
When loading from a file, ensure it contains only JSON.
Avoid hand-editing large batch files; generate them.

When it happens

Trigger: Passing --batch a malformed JSON string (trailing comma, single quotes, unquoted keys, truncated), or pointing --batch at a file whose contents are not valid JSON. A payload that parses but has the wrong shape hits error 95 instead.

Common situations: Shell-quoting loss on a large inline JSON; hand-editing the batch file and leaving a syntax error; UTF-8 BOM or trailing log lines appended to a JSON file; copy-paste that dropped closing brackets.

Related errors

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