What causes "Invalid color-grading ${issue.path}: ${issue.message}.${hint}" in heygen-com/hyperframes?

Read the message: it names the path (e.g. 'grading.wheels.shadows') and the violation; fix that exact location.

heygen-com/hyperframes · error · Error

Invalid color-grading ${issue.path}: ${issue.message}.${hint

Error message

Invalid color-grading ${issue.path}: ${issue.message}.${hint}

What it means

Thrown by assertKnownGradingShape() in packages/cli/src/commands/media-treatment.ts:350. It runs validateColorGradingContract (from @hyperframes/parsers/color-grading-contract) on the --grading value and, if any issue is found, throws the FIRST issue's path, message, and optional hint. This is the structural/shape validator invoked before any patch is merged or written.

Source

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

interface ApplyMediaTreatmentResult {
  html: string;
  changed: boolean;
  tag: "img" | "video";
  value: string | null;
  before: unknown;
  after: unknown;
}

function parseSourceDocument(source: string): Document {
  if (/<!doctype|<html[\s>]/i.test(source)) return parseHTML(source).document;
  return parseHTML(`<!DOCTYPE html><html><body>${source}</body></html>`).document;
}

function assertKnownGradingShape(value: unknown): void {
  const issue = validateColorGradingContract(value)[0];
  if (issue) {
    const hint = issue.hint ? ` ${issue.hint}` : "";
    throw new Error(`Invalid color-grading ${issue.path}: ${issue.message}.${hint}`);
  }
}

function containsColorGradingVariableRef(value: unknown): boolean {
  if (isColorGradingVariableRef(value)) return true;
  if (Array.isArray(value)) return value.some(containsColorGradingVariableRef);
  if (typeof value !== "object" || value === null) return false;
  return Object.values(value).some(containsColorGradingVariableRef);
}

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

function parseStoredGrading(raw: string | null): unknown {
  if (raw === null) return null;
  try {
    return JSON.parse(raw);

View on GitHub (pinned to c2996c8626)

Solutions

Read the message: it names the path (e.g. 'grading.wheels.shadows') and the violation; fix that exact location.
Inspect the canonical contract: `hyperframes media-treatment --capability grading --json` (and per-control: --capability wheels / curves / hue-curves / secondary).
Validate the JSON parses first (a separate 'Could not parse --grading JSON' error covers parse failures).
After editing, run with --dry-run --json to re-validate before writing.

Example fix

# before -- bad shape (shadows at top level)
hyperframes media-treatment -s '#hero' \
  --grading '{"shadows":{"hue":200}}' --apply
# after -- shadows belongs under wheels
hyperframes media-treatment -s '#hero' \
  --grading '{"wheels":{"shadows":{"hue":200,"amount":0.1,"level":0}}}' --apply

Defensive patterns

Strategy: validation

Validate before calling

import { validateColorGradingContract } from '@hyperframes/parsers/color-grading-contract';

function isValidGrading(value: unknown): boolean {
  return validateColorGradingContract(value).length === 0;
}

const parsed = JSON.parse(gradingJson);
if (!isValidGrading(parsed)) {
  throw new Error('Grading JSON violates the contract — see --capability grading');
}

Type guard

import { validateColorGradingContract } from '@hyperframes/parsers/color-grading-contract';

function isValidGradingShape(value: unknown): boolean {
  return validateColorGradingContract(value).length === 0;
}

Try / catch

try {
  applyMediaTreatmentToHtml(source, { selector, grading: parsed, apply: true });
} catch (error) {
  if (/Invalid color-grading/.test(String(error))) {
    // re-fetch the contract for the offending path and surface it to the user
    throw new Error(`Grading rejected: ${error}`);
  }
  throw error;
}

Prevention

Validate grading JSON with validateColorGradingContract before passing it to --grading.
Always run with --dry-run --json first to catch contract issues without writing.
Pull control shapes from `--capability <family>` rather than guessing.

When it happens

Trigger: Passing `--grading '<json>'` whose shape violates the contract: unknown top-level keys, wrong type for a section (e.g. wheels as a string), out-of-range numeric values, malformed curve points, or unknown secondary/palette shape.

Common situations: Hand-typed grading JSON with a typo'd section name; placing top-level keys (like 'shadows') directly under grading instead of under 'wheels'; using control names from a different CLI version; numeric values outside the documented bounds.

Related errors

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