{"record":{"id":"28622d2c3761a171","repo":"heygen-com/hyperframes","slug":"reference-frame-not-found-framepath","errorCode":null,"errorMessage":"Reference frame not found: ${framePath}","messagePattern":"Reference frame not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/grade-compare.ts","lineNumber":519,"sourceCode":"      outPath,\n    ];\n    const result = await runFfmpegOnce(ffmpegPath, args, FFMPEG_EXTRACT_TIMEOUT_MS);\n    if (result.timedOut) {\n      throw new Error(`ffmpeg timed out extracting first frame from ${videoPath}`);\n    }\n    if (result.code !== 0 || !existsSync(outPath)) {\n      const detail = result.stderr.trim() ? `: ${result.stderr.trim()}` : \"\";\n      throw new Error(`ffmpeg could not extract first frame from ${videoPath}${detail}`);\n    }\n    return readFileSync(outPath);\n  } finally {\n    rmSync(tmp, { recursive: true, force: true });\n  }\n}\n\nasync function loadReferenceFrame(framePath: string): Promise<ReferenceFrame> {\n  if (!existsSync(framePath)) {\n    throw new Error(`Reference frame not found: ${framePath}`);\n  }\n\n  const buffer = isVideoPath(framePath)\n    ? await extractVideoFrameToBuffer(framePath)\n    : readFileSync(framePath);\n  if (!buffer) {\n    throw new Error(`Could not extract a frame from video: ${framePath}`);\n  }\n\n  const metadata = await sharp(buffer).metadata();\n  if (!metadata.width || !metadata.height) {\n    throw new Error(`Could not read reference frame dimensions: ${framePath}`);\n  }\n\n  return {\n    buffer,\n    width: metadata.width,\n    height: metadata.height,","sourceCodeStart":501,"sourceCodeEnd":537,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/grade-compare.ts#L501-L537","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `ls <path-from-message>` to confirm it really is missing.","Pass `--project <dir>` so the relative `--for` path resolves from the correct base, or use an absolute path.","Check filename casing exactly, especially on Linux CI that mirrors a macOS working copy."],"exampleFix":"# before\nhyperframes grade-compare --for Frame.PNG --grades g.json  # wrong case\n# after\nhyperframes grade-compare --for frame.png --grades g.json","handlingStrategy":"validation","validationCode":"// Confirm the reference frame exists before invoking grade-compare\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nfunction assertFrameExists(projectDir: string, frame: string): void {\n  if (!existsSync(resolve(projectDir, frame))) {\n    throw new Error(`Reference frame not found: ${resolve(projectDir, frame)}`);\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  // run grade-compare\n} catch (err) {\n  if (/Reference frame not found/.test((err as Error).message))) {\n    // ls the path in the message; fix casing/cwd; re-run\n  }\n}","preventionTips":["Always pass --project to make relative --for paths deterministic.","On case-sensitive filesystems (Linux CI), verify exact filename casing.","Assert the file exists in your script before invoking grade-compare."],"tags":["cli","filesystem","grade-compare","input-validation","path-resolution"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}