heygen-com/hyperframes · error · Error

--luts must include at least one LUT path

Error message

--luts must include at least one LUT path

What it means

Thrown by resolveLutCells when the `--luts` argument, after splitting on commas and trimming, yields zero non-empty paths. The flag is declared optional at the citty layer, so an empty or all-whitespace value reaches this function and is rejected here rather than rendering an empty sheet.

Source

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

    }
    const label = entry.label;
    if (typeof label !== "string" || !label.trim()) {
      throw new Error(`Grade entry ${index + 1} must have a non-empty string label`);
    }
    if (!hasOwn(entry, "grading")) {
      throw new Error(`Grade entry "${label}" must include a grading value`);
    }
    return validateCell(label, entry.grading);
  });
}

export function resolveLutCells(luts: string): GradeCompareCell[] {
  const paths = luts
    .split(",")
    .map((part) => part.trim())
    .filter(Boolean);
  if (paths.length === 0) {
    throw new Error("--luts must include at least one LUT path");
  }
  return paths.map((lutPath) =>
    validateCell(basename(lutPath, extname(lutPath)), { lut: { src: lutPath } }),
  );
}

// The ungraded frame as a leading reference cell. An empty grading object
// normalizes to inactive, so the runtime renders the source image untouched —
// giving the agent a baseline to judge every candidate look against.
export function prependBaselineCell(cells: GradeCompareCell[]): GradeCompareCell[] {
  return [validateCell("original", {}), ...cells];
}

export function parseGradeCompareArgs(args: {
  for?: unknown;
  grades?: unknown;
  luts?: unknown;
  project?: unknown;

View on GitHub (pinned to c2996c8626)

Solutions

1. Supply at least one real .cube path: `--luts looks/a.cube,looks/b.cube`.
2. If the value comes from a variable, guard it in the shell first: `[ -n "$LUTS" ] && hyperframes grade-compare --for f.png --luts "$LUTS"`.
3. Switch to `--grades grades.json` if you want to define looks inline rather than as file paths.

Example fix

# before
hyperframes grade-compare --for frame.png --luts ""
# after
hyperframes grade-compare --for frame.png --luts looks/warm.cube,looks/cool.cube

// Validate a --luts string before passing it
defineLutsArg(raw: string): string[] {
  const paths = raw.split(",").map((p) => p.trim()).filter(Boolean);
  if (paths.length === 0) throw new Error("--luts needs at least one .cube path");
  return paths;
}

function isNonEmptyLutList(s: string): boolean {
  return s.split(",").map((p) => p.trim()).filter(Boolean).length > 0;
}

try {
  const cells = resolveLutCells(lutsArg);
} catch (err) {
  console.error((err as Error).message); // already actionable
  process.exit(1);
}

When it happens

Trigger: Passing `--luts ""`, `--luts ",,"`, or `--luts " "` to `hyperframes grade-compare`. Also hit by a direct call `resolveLutCells("")` or `resolveLutCells(",,")`.

Common situations: Shell quoting that swallows the value (e.g. an unset env var inside the quoted string); a script templating `--luts ${LUTS}` where LUTS is empty; trailing-comma typos.

Related errors

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

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