heygen-com/hyperframes · error · Error

Reference frame not found: ${framePath}

Error message

Reference frame not found: ${framePath}

What it means

Thrown by loadReferenceFrame when the `--for` path does not exist on disk (existsSync is false). This fires before any attempt to read or decode, so the user gets a clear filesystem-level error instead of a downstream ENOENT from readFileSync or an opaque sharp failure.

Source

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

      outPath,
    ];
    const result = await runFfmpegOnce(ffmpegPath, args, FFMPEG_EXTRACT_TIMEOUT_MS);
    if (result.timedOut) {
      throw new Error(`ffmpeg timed out extracting first frame from ${videoPath}`);
    }
    if (result.code !== 0 || !existsSync(outPath)) {
      const detail = result.stderr.trim() ? `: ${result.stderr.trim()}` : "";
      throw new Error(`ffmpeg could not extract first frame from ${videoPath}${detail}`);
    }
    return readFileSync(outPath);
  } finally {
    rmSync(tmp, { recursive: true, force: true });
  }
}

async function loadReferenceFrame(framePath: string): Promise<ReferenceFrame> {
  if (!existsSync(framePath)) {
    throw new Error(`Reference frame not found: ${framePath}`);
  }

  const buffer = isVideoPath(framePath)
    ? await extractVideoFrameToBuffer(framePath)
    : readFileSync(framePath);
  if (!buffer) {
    throw new Error(`Could not extract a frame from video: ${framePath}`);
  }

  const metadata = await sharp(buffer).metadata();
  if (!metadata.width || !metadata.height) {
    throw new Error(`Could not read reference frame dimensions: ${framePath}`);
  }

  return {
    buffer,
    width: metadata.width,
    height: metadata.height,

View on GitHub (pinned to c2996c8626)

Solutions

1. Run `ls <path-from-message>` to confirm it really is missing.
2. Pass `--project <dir>` so the relative `--for` path resolves from the correct base, or use an absolute path.
3. Check filename casing exactly, especially on Linux CI that mirrors a macOS working copy.

Example fix

# before
hyperframes grade-compare --for Frame.PNG --grades g.json  # wrong case
# after
hyperframes grade-compare --for frame.png --grades g.json

// Confirm the reference frame exists before invoking grade-compare
import { existsSync } from "node:fs";
import { resolve } from "node:path";
function assertFrameExists(projectDir: string, frame: string): void {
  if (!existsSync(resolve(projectDir, frame))) {
    throw new Error(`Reference frame not found: ${resolve(projectDir, frame)}`);
  }
}

try {
  // run grade-compare
} catch (err) {
  if (/Reference frame not found/.test((err as Error).message))) {
    // ls the path in the message; fix casing/cwd; re-run
  }
}

When it happens

Trigger: Passing `--for nonexistent.png`; a typo in the filename; running from a cwd where the relative path doesn't resolve; the file was deleted between arg parse and load.

Common situations: Wrong cwd (relative path resolves against `--project`/cwd); case mismatch on case-sensitive filesystems; a build step that was supposed to produce the frame hasn't run; pointing at a file inside a not-yet-cloned repo.

Related errors

• LUT file not found for "${cell.label}": ${sourcePath}
• Grade entry "${label}" must include a grading value
• --luts must include at least one LUT path
• --for <path> is required
• Exactly one of --grades or --luts is required

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