{"record":{"id":"71f78add5c5f10fd","repo":"heygen-com/hyperframes","slug":"invalid-vars","errorCode":"invalid-vars","errorMessage":"--vars must be a JSON object of variable values","messagePattern":"--vars must be a JSON object of variable values","errorType":"validation","errorClass":"AddError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/add.ts","lineNumber":109,"sourceCode":"        : \"\";\n    const vars = variableValuesAttribute(values);\n    return `<div data-composition-src=\"${relativeTarget}\" data-duration=\"${item.duration}\"${dims}${vars}></div>`;\n  }\n  if (item.type === \"hyperframes:component\") {\n    return `<!-- paste from ${relativeTarget} into your composition -->`;\n  }\n  return \"\";\n}\n\n/** `--vars` is JSON an agent or the catalog page produced; a malformed one is\n *  worth a clear error rather than a snippet that silently drops the values. */\nexport function parseVariableValues(raw: string | undefined): Record<string, unknown> | null {\n  if (raw === undefined) return null;\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    throw new AddError(\"--vars must be a JSON object of variable values\", \"invalid-vars\");\n  }\n  if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n    throw new AddError(\"--vars must be a JSON object of variable values\", \"invalid-vars\");\n  }\n  return parsed as Record<string, unknown>;\n}\n\n// ── Core runner (tested) ────────────────────────────────────────────────────\n\nexport interface RunAddArgs {\n  name: string;\n  projectDir: string;\n  skipClipboard?: boolean;\n  /** Variable values to bake into the printed mount snippet. */\n  vars?: string;\n  /** Overwrite files this project has changed since they were installed. */\n  force?: boolean;\n  /** Current CLI version used for registry metadata compatibility checks. */","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/add.ts#L91-L127","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Quote the entire --vars value in the shell and validate it with a JSON linter or `echo '<json>' | jq .`.","Use double quotes for keys and string values, no trailing commas.","Read the value from a file if the payload is large or shell-quoting is fragile."],"exampleFix":"# before: unquoted, invalid JSON\nhyperframes add my-block --vars {color:red,}\n\n# after: quoted, strict JSON\nhyperframes add my-block --vars '{\"color\":\"red\"}'","handlingStrategy":"validation","validationCode":"function safeParseVars(raw: string | undefined): Record<string, unknown> | null {\n  if (raw === undefined) return null;\n  try { JSON.parse(raw); return null; }   // will not throw if valid\n  catch { throw new Error(`--vars is not valid JSON; validate with: echo '${raw}' | jq .`); }\n}","typeGuard":null,"tryCatchPattern":"try {\n  parseVariableValues(varsArg);\n} catch (err) {\n  if (err instanceof AddError && err.code === 'invalid-vars') {\n    // prompt user for corrected JSON or read from file\n  }\n}","preventionTips":["Always single-quote the --vars value in the shell to protect inner double quotes.","Validate with `jq .` before passing.","For complex payloads, read from a file to dodge shell quoting."],"tags":["cli","validation","json","vars"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}