What causes "LUT file not found for "${cell.label}": ${sourcePath}" in heygen-com/hyperframes?

Check the resolved path in the error message — it shows exactly where HyperFrames looked.

heygen-com/hyperframes · error · Error

LUT file not found for "${cell.label}": ${sourcePath}

Error message

LUT file not found for "${cell.label}": ${sourcePath}

What it means

Thrown by prepareGradeCompareTempProject when a cell's grading references a LUT (via `lut: { src }` or `lut: "path"`) but the resolved source file does not exist on disk. The path is resolved relative to projectDir (the `--project` flag or cwd), so a wrong base or a typo produces this rather than a silent ungraded render.

Source

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

  frameBuffer: Buffer;
  cells: readonly GradeCompareCell[];
  frameWidth: number;
  frameHeight: number;
  frameFileName?: string;
}): Promise<PreparedGradeCompareProject> {
  const tempDir = mkdtempSync(join(tmpdir(), "hf-grade-compare-"));
  try {
    const frameFileName = opts.frameFileName ?? frameFileNameForPath(opts.framePath);
    writeFileSync(join(tempDir, frameFileName), opts.frameBuffer);

    let lutIndex = 0;
    const stagedCells = opts.cells.map((cell) => {
      const lutSrc = lutSrcFromGrading(cell.grading);
      if (!lutSrc) return cell;

      const sourcePath = resolveFromBase(opts.projectDir, lutSrc);
      if (!existsSync(sourcePath)) {
        throw new Error(`LUT file not found for "${cell.label}": ${sourcePath}`);
      }
      const lutText = readFileSync(sourcePath, "utf-8");
      try {
        parseCubeLut(lutText, { maxSize: 64 });
      } catch (err) {
        throw new Error(
          `LUT for "${cell.label}" is not a valid .cube: ${normalizeErrorMessage(err)}`,
        );
      }
      const lutExt = extname(sourcePath) || ".cube";
      const stagedName = `lut-${lutIndex}${lutExt}`;
      lutIndex += 1;
      copyFileSync(sourcePath, join(tempDir, stagedName));
      return {
        label: cell.label,
        grading: rewriteGradingLutSrc(cell.grading, stagedName),
      };
    });

View on GitHub (pinned to c2996c8626)

Solutions

Check the resolved path in the error message — it shows exactly where HyperFrames looked.
Pass `--project <dir>` so relative LUT paths resolve from the correct base, or use absolute paths in the grades file.
Verify the file exists with `ls <resolvedPath>` and fix the casing/path.

Example fix

# before — run from wrong dir, relative LUT missing
hyperframes grade-compare --for f.png --grades g.json
# after — set the base dir
hyperframes grade-compare --for f.png --grades g.json --project /path/to/project

Defensive patterns

Strategy: validation

Validate before calling

// Verify every referenced LUT exists before staging
import { existsSync } from "node:fs";
import { resolve } from "node:path";
function assertLutsExist(cells: { label: string; grading: unknown }[], projectDir: string): void {
  for (const cell of cells) {
    const src = lutSrcFromGrading(cell.grading); // reuse the helper
    if (src && !existsSync(resolve(projectDir, src))) {
      throw new Error(`LUT for "${cell.label}" missing: ${resolve(projectDir, src)}`);
    }
  }
}

Type guard

function lutSrcFromGrading(g: unknown): string | null {
  if (typeof g !== "object" || g === null || Array.isArray(g)) return null;
  const lut = (g as any).lut;
  if (typeof lut === "string" && lut.trim()) return lut.trim();
  if (typeof lut === "object" && lut !== null && typeof lut.src === "string" && lut.src.trim()) return lut.src.trim();
  return null;
}

Try / catch

try {
  await prepareGradeCompareTempProject(opts);
} catch (err) {
  if (/LUT file not found/.test((err as Error).message))) {
    // message includes the resolved path — ls it and fix the grades JSON or cwd
  }
  throw err;
}

Prevention

Always pass --project when using relative LUT paths so resolution is deterministic.
In CI, run from the repo root or use absolute LUT paths.
Check LUT existence in a pre-flight step before invoking grade-compare.

When it happens

Trigger: A grades JSON entry whose `grading.lut.src` (or string `grading.lut`) points to a missing file; a `--luts` path that doesn't exist; running from a different cwd so a relative LUT path no longer resolves.

Common situations: Moving the project directory without moving the LUTs; relative paths that worked in one cwd but break in CI; case-sensitivity differences between macOS and Linux CI; a typo in the LUT filename.

Related errors

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