heygen-com/hyperframes · error · AddError

invalid-vars

invalid-vars

Error message

--vars must be a JSON object of variable values

What it means

AddError with code 'invalid-vars', thrown by parseVariableValues when JSON.parse(raw) throws on the --vars string. The function exists precisely to give a clear, code-stamped error instead of letting a malformed snippet silently drop the variable values. A subsequent check (error 88) handles the case where JSON parses but is not a plain object.

Source

Thrown at packages/cli/src/commands/add.ts:109

        : "";
    const vars = variableValuesAttribute(values);
    return `<div data-composition-src="${relativeTarget}" data-duration="${item.duration}"${dims}${vars}></div>`;
  }
  if (item.type === "hyperframes:component") {
    return `<!-- paste from ${relativeTarget} into your composition -->`;
  }
  return "";
}

/** `--vars` is JSON an agent or the catalog page produced; a malformed one is
 *  worth a clear error rather than a snippet that silently drops the values. */
export function parseVariableValues(raw: string | undefined): Record<string, unknown> | null {
  if (raw === undefined) return null;
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    throw new AddError("--vars must be a JSON object of variable values", "invalid-vars");
  }
  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new AddError("--vars must be a JSON object of variable values", "invalid-vars");
  }
  return parsed as Record<string, unknown>;
}

// ── Core runner (tested) ────────────────────────────────────────────────────

export interface RunAddArgs {
  name: string;
  projectDir: string;
  skipClipboard?: boolean;
  /** Variable values to bake into the printed mount snippet. */
  vars?: string;
  /** Overwrite files this project has changed since they were installed. */
  force?: boolean;
  /** Current CLI version used for registry metadata compatibility checks. */

View on GitHub (pinned to c2996c8626)

Solutions

1. Quote the entire --vars value in the shell and validate it with a JSON linter or `echo '<json>' | jq .`.
2. Use double quotes for keys and string values, no trailing commas.
3. Read the value from a file if the payload is large or shell-quoting is fragile.

Example fix

# before: unquoted, invalid JSON
hyperframes add my-block --vars {color:red,}

# after: quoted, strict JSON
hyperframes add my-block --vars '{"color":"red"}'

function safeParseVars(raw: string | undefined): Record<string, unknown> | null {
  if (raw === undefined) return null;
  try { JSON.parse(raw); return null; }   // will not throw if valid
  catch { throw new Error(`--vars is not valid JSON; validate with: echo '${raw}' | jq .`); }
}

try {
  parseVariableValues(varsArg);
} catch (err) {
  if (err instanceof AddError && err.code === 'invalid-vars') {
    // prompt user for corrected JSON or read from file
  }
}

When it happens

Trigger: Passing --vars with a typo'd JSON literal: trailing comma, single quotes, unquoted keys, an unterminated string, or a shell that ate the quotes and left a bare token. Any input that is valid JSON but is not reached here if it parses successfully.

Common situations: Shell quoting mistakes (hyperframes add block --vars {foo:bar} without quotes), copy-paste from a doc that lost the outer quotes, trailing comma from hand-editing, or JSON5/JS-literal syntax mistakenly used.

Related errors

• ${source}: ${errorMessage(error)}
• --batch must be a JSON array of objects, or an object with a
• [validateConfig] config: Step Functions execution input is n
• [validateConfig] config: Step Functions execution input is n
• ${source} contains zero rows.

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