heygen-com/hyperframes · error · Error

Could not parse --grading JSON: ${normalizeErrorMessage(erro

Error message

Could not parse --grading JSON: ${normalizeErrorMessage(error)}

What it means

Thrown by parseGrading when JSON.parse(raw) throws on the --grading string. The value must be valid JSON conforming to the HyperFrames color-grading contract. The wrapped normalizeErrorMessage extracts the underlying SyntaxError detail (unexpected token, trailing comma, etc.).

Source

Thrown at packages/cli/src/commands/media-treatment.ts:526

  return asset.resolved;
}

function parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {
  if (clear) {
    if (raw !== undefined || apply) {
      throw new Error("Use either --apply with --grading or --clear, not both");
    }
    return undefined;
  }
  if (!apply) {
    if (raw !== undefined) throw new Error("--grading requires --apply");
    throw new Error("Use --apply with --grading <json> or --clear");
  }
  if (raw === undefined) throw new Error("--apply requires --grading <json>");
  try {
    return JSON.parse(raw);
  } catch (error) {
    throw new Error(`Could not parse --grading JSON: ${normalizeErrorMessage(error)}`);
  }
}

function mutationVerb(action: "apply" | "clear", changed: boolean, dryRun: boolean): string {
  if (dryRun) return `Would ${action}`;
  if (!changed) return action === "apply" ? "Already applied" : "Already clear";
  return action === "apply" ? "Applied" : "Cleared";
}

interface MediaTreatmentCommandArgs {
  capabilities?: boolean;
  capability?: string;
  all?: boolean;
  project?: string;
  file?: string;
  selector?: string;
  "selector-index"?: string;
  grading?: string;

View on GitHub (pinned to c2996c8626)

Solutions

1. Use strictly valid JSON: double-quoted keys and string values, no trailing commas
2. Single-quote the whole argument in the shell and use double quotes inside: --grading '{"preset":"warm"}'
3. Validate the JSON with a linter or `echo '<json>' | jq .` before passing it
4. Discover valid shapes via `hyperframes media-treatment --capability <id> --json`

Example fix

// before — single quotes inside, invalid JSON
hyperframes media-treatment --selector '#hero' --grading "{'preset':'warm'}" --apply
// after — valid JSON, shell-single-quoted
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply

function tryParseGradingJson(raw: string): unknown {
  try {
    return JSON.parse(raw);
  } catch (e) {
    throw new Error(`Invalid grading JSON: ${(e as Error).message}. Use double-quoted keys/values.`);
  }
}
// validate before building the CLI command
const parsed = tryParseGradingJson(gradingArg);

try {
  JSON.parse(gradingRaw);
} catch (e) {
  // surface a hint about double quotes / no trailing commas, then re-prompt
}

When it happens

Trigger: Passing single-quoted JSON (shell-style), trailing commas, unquoted keys, or a preset name string without object wrapping. Example: --grading "{preset:'warm'}" fails because keys/values need double quotes.

Common situations: Shell quoting issues (single quotes inside double quotes). Hand-written JSON with JS-object shorthand. Copy-pasting from JS source where keys are unquoted. Trailing commas from edited JSON.

Related errors

• --selector-index must be a non-negative integer
• Media analysis requires a local project asset; freeze remote
• Use either --apply with --grading or --clear, not both
• --grading requires --apply
• --apply requires --grading <json>

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