heygen-com/hyperframes · error · Error

--selector is required

Error message

--selector is required

What it means

Thrown by analyzeTarget when --analyze is set but no --selector is provided. The analyze operation must target exactly one media element to measure, so a CSS selector is mandatory. Without it the command cannot know which <img>/<video> to read.

Source

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

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

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 {

View on GitHub (pinned to c2996c8626)

Solutions

1. Add a CSS selector targeting one <img> or <video>: `--selector '#hero' --analyze`
2. Use --selector-index if the selector matches multiple elements
3. Inspect the composition HTML to find a unique selector for the media element

Example fix

// before
hyperframes media-treatment --analyze
// after
hyperframes media-treatment --selector '#hero' --analyze

function requireSelectorForAnalyze(selector?: string): void {
  if (!selector) throw new Error('--selector is required for --analyze');
}

When it happens

Trigger: Running `hyperframes media-treatment --analyze` or `hyperframes media-treatment --analyze --json` with no --selector argument.

Common situations: Agents that assume --analyze inspects all media. Users who forget the selector when switching from --capabilities to --analyze.

Related errors

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