What causes "Could not parse grades JSON: ${normalizeErrorMessage(err)}" in heygen-com/hyperframes?

Validate the file with a JSON linter or `node -e 'JSON.parse(require("fs").readFileSync("grades.json","utf8"))'`

heygen-com/hyperframes · error · Error

Could not parse grades JSON: ${normalizeErrorMessage(err)}

Error message

Could not parse grades JSON: ${normalizeErrorMessage(err)}

What it means

Thrown by parseGradesFile() when JSON.parse throws on the file contents. The inner error message is normalized and appended. The parser uses strict JSON — no comments, no trailing commas, no unquoted keys, no JSON5/JSONC.

Source

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

  }
  if (isRecord(lut)) {
    const nextLut = cloneRecord(lut);
    nextLut.src = src;
    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);

View on GitHub (pinned to c2996c8626)

Solutions

Validate the file with a JSON linter or `node -e 'JSON.parse(require("fs").readFileSync("grades.json","utf8"))'`
Use strict JSON: double quotes, no comments, no trailing commas
Re-save the file as plain UTF-8 without BOM

Example fix

// before (unquoted keys, trailing comma)
{
  label: "warm",
  grading: {},
}
// after
[
  { "label": "warm", "grading": {} }
]

Defensive patterns

Strategy: validation

Validate before calling

try {
  JSON.parse(readFileSync(filePath, 'utf-8'));
} catch (err) {
  throw new Error(`grades JSON is invalid: ${(err as Error).message}`);
}

Try / catch

try {
  parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
} catch (err) {
  // Surface a targeted message with the file path and the parser's position.
  throw new Error(`Could not parse grades JSON in ${filePath}: ${(err as Error).message}`);
}

Prevention

Use strict JSON: double quotes, no comments, no trailing commas
Run the file through a JSON linter or `node -e JSON.parse(...)` before the command
Save as plain UTF-8 without a BOM

When it happens

Trigger: A trailing comma; unquoted keys; // or /* */ comments; single-quoted strings; smart/curly quotes pasted from a doc; a truncated file; a UTF-8 BOM that trips strict parsing.

Common situations: Hand-editing the grades file and treating it as JSONC; pasting an example that used typographic quotes; an editor that strips the final brace.

Related errors

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