heygen-com/hyperframes · error · Error

Invalid color grading for cell "${label}"

Error message

Invalid color grading for cell "${label}"

What it means

Thrown by validateCell() in grade-compare when normalizeHfColorGrading(grading) returns null. normalize returns null when readColorGradingObject yields nothing — empty/whitespace string, a malformed JSON string not starting with '{', a non-object primitive (number, null, undefined), an array, or an object with enabled:false. Note: a bare object {} is VALID (it normalizes to an inactive baseline) — only enabled:false or unparseable shapes are rejected.

Source

Thrown at packages/cli/src/commands/grade-compare.ts:135

  return value
    .replace(/&/g, "&")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&apos;");
}

function escapeSingleQuotedAttr(value: string): string {
  return value
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/'/g, "&#39;");
}

function validateCell(label: string, grading: unknown): GradeCompareCell {
  if (!normalizeHfColorGrading(grading)) {
    throw new Error(`Invalid color grading for cell "${label}"`);
  }
  return { label, grading };
}

export function warnInactiveGradingCells(cells: readonly GradeCompareCell[]): void {
  for (const cell of cells) {
    const normalized = normalizeHfColorGrading(cell.grading);
    if (!isHfColorGradingActive(normalized)) {
      console.error(
        c.warn(`Warning: grading for "${cell.label}" is inactive/no-op — it will render ungraded`),
      );
    }
  }
}

export function capCandidateCells(cells: readonly GradeCompareCell[]): CandidateCellCapResult {
  const total = cells.length;
  if (total <= MAX_CANDIDATE_CELLS) {

View on GitHub (pinned to c2996c8626)

Solutions

1. Make grading an object — even {} is valid (renders as the inactive baseline)
2. Use a preset name string, e.g. "cinematic", which readColorGradingObject accepts
3. Remove enabled:false (or set it to true) so normalize does not short-circuit to null

Example fix

// before
[
  { "label": "warm", "grading": null }
]
// after
[
  { "label": "warm", "grading": {} }
]
// or
[
  { "label": "warm", "grading": "cinematic" }
]

import { normalizeHfColorGrading } from '@hyperframes/core';
if (!normalizeHfColorGrading(grading)) {
  throw new Error(`grading for ${label} is invalid (use an object, a preset name, or remove enabled:false)`);
}

import { normalizeHfColorGrading } from '@hyperframes/core';
function isValidGrading(grading: unknown): boolean {
  return normalizeHfColorGrading(grading) !== null;
}

When it happens

Trigger: A grades.json entry with grading: null, "", 42, [], "{bad json", or { enabled: false }; passing undefined where a grading object is expected.

Common situations: Hand-writing grades.json and using null/empty as a placeholder; copying a grading snippet that had enabled:false; a schema drift after a library version change.

Related errors

• Invalid color grading for cell "${cell.label}"
• Grades file not found: ${filePath}
• Could not parse grades JSON: ${normalizeErrorMessage(err)}
• Grades file must be a JSON array of { label, grading } objec
• Grade entry ${index + 1} must be an object with label and gr

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