heygen-com/hyperframes · error · Error

Grades file not found

Error message

Grades file not found: ${filePath}

What it means

Thrown by parseGradesFile() as its first check: existsSync(filePath) must be true. The filePath is already resolved against projectDir by parseGradeCompareArgs before this function is called, so the message shows the absolute path that was searched.

Solutions

1. Pass an absolute path, or one relative to --project (the resolution base)
2. Verify with `ls <path>` from the same directory you pass as --project
3. Check spelling and case exactly

Example fix

// before (wrong base / typo)
hyperframes grade-compare --for f.png --grades grades.json --project ./reels
// after (absolute, or correct relative path)
hyperframes grade-compare --for f.png --grades /abs/reels/grades.json --project ./reels

import { existsSync } from 'node:fs';
if (!existsSync(filePath)) {
  throw new Error(`grades file not found: ${filePath}`);
}

When it happens

Trigger: `--grades missing.json`; a relative path resolved against a --project dir where the file does not exist; a typo; case mismatch on a case-sensitive filesystem; the path points at a directory instead of a file.

Common situations: Running the command from a different cwd than expected; using a path relative to the shell cwd while --project points elsewhere; copying a path from another machine with a different layout.

Related errors

• Composition file not found
• Could not parse grades JSON
• Could not read reference frame dimensions
• Grade entry must be an object with label and grading
• Grade entry must have a non-empty string label

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

Appendix: source

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

function rewriteGradingLutSrc(grading: unknown, src: string): unknown {
  if (!isRecord(grading) || !hasOwn(grading, "lut")) return grading;
  const lut = grading.lut;
  const next = cloneRecord(grading);
  if (typeof lut === "string") {
    next.lut = { src };
    return next;
  }
  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;

View on GitHub (pinned to c2996c8626)