heygen-com/hyperframes · error · Error

--apply requires --grading <json>

Error message

--apply requires --grading <json>

What it means

Thrown by parseGrading when --apply is set but --grading <json> is not provided. The --apply flag is an explicit verb that requires a payload to apply; without --grading there is nothing to write. The CLI rejects this rather than silently no-oping.

Source

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

    ? 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;
  capability?: string;
  all?: boolean;
  project?: string;

View on GitHub (pinned to c2996c8626)

Solutions

1. Provide a grading payload: `--grading '<json>' --apply`
2. If you meant to clear, use `--clear` instead of `--apply`
3. Use `--capabilities` or `--capability <id>` to discover valid grading shapes

Example fix

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

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

When it happens

Trigger: Running `hyperframes media-treatment --selector '#hero' --apply` with no --grading value. Common in agent flows that set --apply as a marker but forget to attach the grading JSON.

Common situations: Agent command builders that conditionally attach --apply but miss the --grading payload. Users who assume --apply alone re-applies a previous grading.

Related errors

• --grading requires --apply
• --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/7f56c08852d91e2a. Report an issue: GitHub.