heygen-com/hyperframes · error · Error

Grades file must be a JSON array of { label, grading } objec

Error message

Grades file must be a JSON array of { label, grading } objects

What it means

Thrown by parseGradesFile() after a successful JSON.parse: the top-level value must be an array (Array.isArray). Each element becomes one grade cell, so a bare object or scalar is rejected. The message states the expected element shape { label, grading }.

Source

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

    next.lut = nextLut;
  }
  return next;
}

export function parseGradesFile(filePath: string): GradeCompareCell[] {
  if (!existsSync(filePath)) {
    throw new Error(`Grades file not found: ${filePath}`);
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(readFileSync(filePath, "utf-8"));
  } catch (err) {
    throw new Error(`Could not parse grades JSON: ${normalizeErrorMessage(err)}`);
  }

  if (!Array.isArray(parsed)) {
    throw new Error("Grades file must be a JSON array of { label, grading } objects");
  }

  return parsed.map((entry, index) => {
    if (!isRecord(entry)) {
      throw new Error(`Grade entry ${index + 1} must be an object with label and grading`);
    }
    const label = entry.label;
    if (typeof label !== "string" || !label.trim()) {
      throw new Error(`Grade entry ${index + 1} must have a non-empty string label`);
    }
    if (!hasOwn(entry, "grading")) {
      throw new Error(`Grade entry "${label}" must include a grading value`);
    }
    return validateCell(label, entry.grading);
  });
}

export function resolveLutCells(luts: string): GradeCompareCell[] {

View on GitHub (pinned to c2996c8626)

Solutions

1. Make the top-level value a JSON array
2. Move any wrapper object's contents out to the array root
3. Confirm with `JSON.parse` + `Array.isArray` in a quick script

Example fix

// before
{
  "cells": [
    { "label": "warm", "grading": {} }
  ]
}
// after
[
  { "label": "warm", "grading": {} }
]

if (!Array.isArray(parsed)) {
  throw new Error('grades file top-level must be a JSON array of { label, grading } objects');
}

function isGradesArray(parsed: unknown): parsed is unknown[] {
  return Array.isArray(parsed);
}

When it happens

Trigger: Top-level is an object wrapper like { "cells": [...] }; a single grade object instead of a one-element array; top-level is a number/string/boolean.

Common situations: Wrapping the array in a container object for documentation purposes; exporting a single preset as an object from another tool; a schema mismatch.

Related errors

• Grade entry ${index + 1} must be an object with label and gr
• Grade entry ${index + 1} must have a non-empty string label
• Could not parse grades JSON: ${normalizeErrorMessage(err)}
• [validateConfig] config: Step Functions execution input is n
• [validateConfig] config: Step Functions execution input is n

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