heygen-com/hyperframes · error · Error

--analyze cannot be combined with mutation options

Error message

--analyze cannot be combined with mutation options

What it means

Thrown by analyzeTarget when --analyze is combined with any of --grading, --clear, --apply, or --dry-run. Analysis is a read-only measurement pass; mutation flags imply a write intent. The two modes are mutually exclusive to keep the command's effect unambiguous.

Source

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

  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 };
}

function analyzeTarget(args: MediaTreatmentCommandArgs) {
  const { project, filePath } = resolveMutationFile(args);
  const selector = readOptionalString(args.selector);
  if (!selector) throw new Error("--selector is required");
  if (
    readOptionalString(args.grading) ||
    args.clear === true ||
    args.apply === true ||
    args["dry-run"] === true
  ) {
    throw new Error("--analyze cannot be combined with mutation options");
  }
  const selectorIndex = parseSelectorIndex(readOptionalString(args["selector-index"]));
  const { element, tag } = selectMediaElement(
    readFileSync(filePath, "utf8"),
    selector,
    selectorIndex,
  );
  const source = mediaSourceForElement(element);
  const compositionFile = relative(project.dir, filePath).split("\\").join("/");
  const mediaPath = resolveMediaTreatmentSource(project.dir, compositionFile, source);
  return {
    ok: true,
    action: "analyze",
    file: compositionFile || "index.html",
    selector,
    selectorIndex: selectorIndex ?? 0,
    tag,
    media: source,

View on GitHub (pinned to c2996c8626)

Solutions

1. Run analysis alone: `--selector '#hero' --analyze`
2. Run mutation separately: `--selector '#hero' --grading '<json>' --apply`
3. To preview a mutation without writing, use `--apply --dry-run` (not --analyze)

Example fix

// before
hyperframes media-treatment --selector '#hero' --analyze --grading '{"preset":"warm"}'
// after — analyze read-only
hyperframes media-treatment --selector '#hero' --analyze

function assertAnalyzeIsolated(args: { analyze?: boolean; grading?: string; clear?: boolean; apply?: boolean; 'dry-run'?: boolean }): void {
  if (args.analyze && (args.grading || args.clear || args.apply || args['dry-run'])) {
    throw new Error('--analyze cannot combine with mutation flags');
  }
}

When it happens

Trigger: Commands like `hyperframes media-treatment --selector '#hero' --analyze --apply` or `--analyze --grading '{...}'` or `--analyze --dry-run`.

Common situations: Agents that chain exploration and mutation in one command. Users who add --dry-run to --analyze thinking it previews a mutation. Flags reused from a prior apply command.

Related errors

• Use either --apply with --grading or --clear, not both
• --capabilities cannot be combined with mutation options
• Use either --all or --capability, not both
• --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/aa75f6489b386359. Report an issue: GitHub.