heygen-com/hyperframes · error · Error

--capabilities cannot be combined with mutation options

Error message

--capabilities cannot be combined with mutation options

What it means

Thrown by runCapabilityQuery when --capabilities (or --capability/--all) is combined with any mutation or analysis option (--selector, --grading, --clear, --dry-run, --apply, --analyze). Capability queries are read-only introspection and must run alone; mixing them with mutations is rejected to prevent ambiguous intent.

Source

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

  grading?: string;
  apply?: boolean;
  analyze?: boolean;
  clear?: boolean;
  "dry-run"?: boolean;
  json?: boolean;
}

function runCapabilityQuery(args: MediaTreatmentCommandArgs): void {
  const capability = readOptionalString(args.capability);
  const hasMutationOption = [
    readOptionalString(args.selector),
    readOptionalString(args.grading),
    args.clear,
    args["dry-run"],
    args.apply,
    args.analyze,
  ].some(Boolean);
  if (hasMutationOption) throw new Error("--capabilities cannot be combined with mutation options");
  if (args.all === true && capability)
    throw new Error("Use either --all or --capability, not both");

  let capabilities: unknown = getMediaTreatmentCapabilityOverview();
  if (args.all === true) capabilities = getHfColorGradingCapabilities();
  else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);
  console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));
}

function resolveMutationFile(args: MediaTreatmentCommandArgs) {
  const project = resolveProject(readOptionalString(args.project));
  const fileArg = readOptionalString(args.file) ?? "index.html";
  const filePath = resolve(project.dir, fileArg);
  if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(".html")) {
    throw new Error("--file must be an HTML file inside the project");
  }
  if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);
  return { project, filePath };

View on GitHub (pinned to c2996c8626)

Solutions

1. Run the capability query on its own: `hyperframes media-treatment --capabilities`
2. Run the mutation as a separate command without --capabilities/--capability/--all
3. Strip all mutation flags before issuing a capability introspection call

Example fix

// before
hyperframes media-treatment --capabilities --selector '#hero' --apply
// after — split into two commands
hyperframes media-treatment --capabilities
hyperframes media-treatment --selector '#hero' --grading '{"preset":"warm"}' --apply

function assertCapabilityQueryIsolated(args: { capabilities?: boolean; capability?: string; all?: boolean; selector?: string; grading?: string; clear?: boolean; apply?: boolean; analyze?: boolean; 'dry-run'?: boolean }): void {
  const isCap = args.capabilities || !!args.capability || args.all;
  const hasMutation = args.selector || args.grading || args.clear || args.apply || args.analyze || args['dry-run'];
  if (isCap && hasMutation) {
    throw new Error('Capability queries must run without mutation/analysis flags');
  }
}

When it happens

Trigger: Commands like `hyperframes media-treatment --capabilities --selector '#hero'` or `--capability wheels --apply`. The presence of any truthy mutation flag alongside a capability query triggers this.

Common situations: Agent command builders that always append --capabilities for context. Users exploring capabilities while reusing a command template that has mutation flags. Flags leaking from a shared base command string.

Related errors

• Use either --apply with --grading or --clear, not both
• 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/410c0fe0256ded6d. Report an issue: GitHub.