{"record":{"id":"dbd0fa86ae770b21","repo":"heygen-com/hyperframes","slug":"could-not-read-reference-frame-dimensions-frame","errorCode":null,"errorMessage":"Could not read reference frame dimensions: ${framePath}","messagePattern":"Could not read reference frame dimensions: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/grade-compare.ts","lineNumber":531,"sourceCode":"    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,\n    stagedName: isVideoPath(framePath) ? \"frame.png\" : frameFileNameForPath(framePath),\n  };\n}\n\nasync function captureGradeCompareSheet(\n  projectDir: string,\n  timeoutMs: number,\n): Promise<{ sheetPath: string; renderReadyTimedOut: boolean }> {\n  const { bundleToSingleHtml } = await import(\"@hyperframes/core/compiler\");\n\n  const html = await bundleToSingleHtml(projectDir);\n  const server = await serveStaticProjectHtml(projectDir, html);","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/grade-compare.ts#L513-L549","documentation":"Thrown by loadReferenceFrame when sharp successfully decoded the buffer but returned no width or height in its metadata. Without dimensions the grid layout cannot size cells, so the command aborts. This typically means the file exists and was read but isn't a decodable image (or is a format sharp's metadata pass can't introspect).","triggerScenarios":"Passing `--for` a file that exists and is non-empty but is not a supported image — a text file, a corrupt/truncated image, an exotic format sharp doesn't ship a decoder for, or a 0-byte image. For video inputs it means the extracted frame PNG was unreadable.","commonSituations":"Renaming a non-image to .png; a partially downloaded/corrupted image; an AVIF or JXL file when the sharp build lacks that codec; a video whose ffmpeg extraction silently produced an empty PNG.","solutions":["Open the named file in an image viewer to confirm it's a valid, complete image.","If it's a video, separately verify ffmpeg can extract a frame (see errors 147/148/150) — the extracted PNG may be corrupt.","Re-encode the image to PNG/JPEG with an image tool, or reinstall sharp with the needed codec support.","Check the file isn't zero bytes (`ls -l <path>`)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify the reference image is decodable with sharp before grading\nimport sharp from \"sharp\";\nimport { readFileSync } from \"node:fs\";\nasync function assertReadableImage(path: string): Promise<void> {\n  const meta = await sharp(readFileSync(path)).metadata();\n  if (!meta.width || !meta.height) throw new Error(`No dimensions in ${path}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  // run grade-compare\n} catch (err) {\n  if (/Could not read reference frame dimensions/.test((err as Error).message))) {\n    // re-encode the image to PNG/JPEG externally, or restore sharp codec support\n  }\n}","preventionTips":["Open reference images in an image viewer to confirm they're complete before grading.","Re-encode exotic formats (AVIF/JXL) to PNG if your sharp build lacks decoders.","Check `ls -l` for zero-byte files after downloads/copies."],"tags":["cli","sharp","image","grade-compare","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}