heygen-com/hyperframes · error · Error

Could not read reference frame dimensions: ${framePath}

Error message

Could not read reference frame dimensions: ${framePath}

What it means

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).

Source

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

    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,
    stagedName: isVideoPath(framePath) ? "frame.png" : frameFileNameForPath(framePath),
  };
}

async function captureGradeCompareSheet(
  projectDir: string,
  timeoutMs: number,
): Promise<{ sheetPath: string; renderReadyTimedOut: boolean }> {
  const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");

  const html = await bundleToSingleHtml(projectDir);
  const server = await serveStaticProjectHtml(projectDir, html);

View on GitHub (pinned to c2996c8626)

Solutions

1. Open the named file in an image viewer to confirm it's a valid, complete image.
2. If it's a video, separately verify ffmpeg can extract a frame (see errors 147/148/150) — the extracted PNG may be corrupt.
3. Re-encode the image to PNG/JPEG with an image tool, or reinstall sharp with the needed codec support.
4. Check the file isn't zero bytes (`ls -l <path>`).

// Verify the reference image is decodable with sharp before grading
import sharp from "sharp";
import { readFileSync } from "node:fs";
async function assertReadableImage(path: string): Promise<void> {
  const meta = await sharp(readFileSync(path)).metadata();
  if (!meta.width || !meta.height) throw new Error(`No dimensions in ${path}`);
}

try {
  // run grade-compare
} catch (err) {
  if (/Could not read reference frame dimensions/.test((err as Error).message))) {
    // re-encode the image to PNG/JPEG externally, or restore sharp codec support
  }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• LUT for "${cell.label}" is not a valid .cube: ${normalizeErr
• invalid-vars
• ${source}: ${errorMessage(error)}
• --batch must be a JSON array of objects, or an object with a
• ${source} contains zero rows.

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