heygen-com/hyperframes · error · Error

Use either --apply with --grading or --clear, not both

Error message

Use either --apply with --grading or --clear, not both

What it means

Thrown by parseGrading when --clear is set simultaneously with --grading or --apply. The command supports exactly two mutation modes: apply a grading patch (--apply --grading <json>) or remove grading (--clear). Combining them is ambiguous and rejected up front.

Source

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

  if (isRemoteOrInlineUrl(sourceUrl)) {
    throw new Error(
      "Media analysis requires a local project asset; freeze remote media with media-use first",
    );
  }
  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";

View on GitHub (pinned to c2996c8626)

Solutions

1. To apply: use `--grading '<json>' --apply` without --clear
2. To remove: use `--clear` alone without --grading or --apply
3. Audit your command string for stale flags before running

Example fix

// before
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply --clear
// after — pick one mode
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply

function validateMutationFlags(opts: { grading?: string; apply?: boolean; clear?: boolean }): void {
  if (opts.clear && (opts.grading !== undefined || opts.apply)) {
    throw new Error('Conflicting flags: --clear cannot combine with --grading or --apply');
  }
}

When it happens

Trigger: Invoking `hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply --clear` or `... --grading '{...}' --clear`. Also fires when --clear is combined with --apply even without --grading.

Common situations: Agent loops that accumulate flags across iterations. Shell scripts that conditionally append flags without resetting. Copy-pasting a command and appending --clear without removing the apply flags.

Related errors

• --capabilities cannot be combined with mutation options
• Use either --all or --capability, not both
• --analyze cannot be combined with mutation options
• --selector-index must be a non-negative integer
• Media analysis requires a local project asset; freeze remote

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