heygen-com/hyperframes · error · Error

--grading requires --apply

Error message

--grading requires --apply

What it means

Thrown by parseGrading when --grading <json> is supplied without --apply and without --clear. The --grading value is a mutation payload; the CLI requires an explicit action verb (--apply) to commit it. Providing grading alone is treated as an incomplete, potentially accidental command.

Source

Thrown at packages/cli/src/commands/media-treatment.ts:519

  const cleanSource = cleanAssetUrl(sourceUrl);
  if (!cleanSource) throw new Error("Selected media has no analyzable local src");
  const projectRelative = cleanSource.startsWith("/")
    ? cleanSource
    : rewriteAssetPath(compositionFile, cleanSource, (path) => existsSync(join(projectDir, path)));
  const asset = resolveExistingLocalAsset(projectDir, projectRelative);
  if (!asset) throw new Error(`Media file not found: ${source}`);
  return asset.resolved;
}

function parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {
  if (clear) {
    if (raw !== undefined || apply) {
      throw new Error("Use either --apply with --grading or --clear, not both");
    }
    return undefined;
  }
  if (!apply) {
    if (raw !== undefined) throw new Error("--grading requires --apply");
    throw new Error("Use --apply with --grading <json> or --clear");
  }
  if (raw === undefined) throw new Error("--apply requires --grading <json>");
  try {
    return JSON.parse(raw);
  } catch (error) {
    throw new Error(`Could not parse --grading JSON: ${normalizeErrorMessage(error)}`);
  }
}

function mutationVerb(action: "apply" | "clear", changed: boolean, dryRun: boolean): string {
  if (dryRun) return `Would ${action}`;
  if (!changed) return action === "apply" ? "Already applied" : "Already clear";
  return action === "apply" ? "Applied" : "Cleared";
}

interface MediaTreatmentCommandArgs {
  capabilities?: boolean;

View on GitHub (pinned to c2996c8626)

Solutions

1. Add --apply to commit the grading: `--grading '<json>' --apply`
2. Add --apply --dry-run to preview without writing
3. If you intended to remove grading, drop --grading and use --clear instead

Example fix

// before
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}'
// after
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply

function requireApplyForGrading(grading?: string, apply?: boolean, clear?: boolean): void {
  if (!clear && !apply && grading !== undefined) {
    throw new Error('--grading requires --apply or --clear');
  }
}

When it happens

Trigger: Running `hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}'` with no --apply and no --clear flag.

Common situations: Agents omitting --apply assuming grading implies application. Users testing a dry-run who forget --apply --dry-run. Copy-paste that drops the trailing flag.

Related errors

• --apply requires --grading <json>
• --selector is required
• --selector-index must be a non-negative integer
• Media analysis requires a local project asset; freeze remote
• Use either --apply with --grading or --clear, not both

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