heygen-com/hyperframes · error · Error

Selector did not match: ${selector}

Error message

Selector did not match: ${selector}

What it means

Thrown by selectMediaElement() in packages/cli/src/commands/media-treatment.ts:427. queryIncludingTemplates returned zero matches for a syntactically valid selector. The check covers both the regular DOM and <template> contents, so a miss means the element genuinely isn't in the parsed source (static HTML, before any runtime JS).

Source

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

    const nested = queryIncludingTemplates(template, selector);
    if (nested.length > 0) return nested;
  }
  return [];
}

function selectMediaElement(
  source: string,
  selector: string,
  selectorIndex?: number,
): { element: Element; selectorIndex: number; tag: "img" | "video" } {
  const document = parseSourceDocument(source);
  let matches: Element[];
  try {
    matches = queryIncludingTemplates(document, selector);
  } catch {
    throw new Error(`Invalid selector: ${selector}`);
  }
  if (matches.length === 0) throw new Error(`Selector did not match: ${selector}`);
  if (selectorIndex === undefined && matches.length > 1) {
    throw new Error(
      `Selector matched ${matches.length} elements; use a unique selector or --selector-index`,
    );
  }

  const resolvedIndex = selectorIndex ?? 0;
  const element = matches[resolvedIndex];
  if (!element) {
    throw new Error(`--selector-index ${resolvedIndex} is outside ${matches.length} matches`);
  }
  const tag = element.tagName.toLowerCase();
  if (tag !== "img" && tag !== "video") {
    throw new Error(`Color grading requires an <img> or <video>; selector matched <${tag}>`);
  }
  return { element, selectorIndex: resolvedIndex, tag };
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Open the exact --file and search for the selector string to confirm it's present in static HTML.
2. If the element is JS-generated, point at the source template/HTML where it's authored, not a runtime snapshot.
3. Broaden the selector (e.g. 'img' instead of '#hero-img') to confirm any match exists, then narrow.
4. Verify the --file path is relative to the project dir and ends in .html.

Example fix

# before
hyperframes media-treatment --file scenes/old.html --selector '#hero' ...
# after -- correct file
hyperframes media-treatment --file scenes/scene.html --selector '#hero' ...

import { parseHTML } from 'linkedom';

function selectorMatchesInSource(selector: string, source: string): boolean {
  const { document } = parseHTML(source);
  return document.querySelectorAll(selector).length > 0;
}

try {
  selectMediaElement(source, selector);
} catch (error) {
  if (/Selector did not match/.test(String(error))) {
    // verify the --file path and that the element exists in static HTML
    throw new Error(`No match for ${selector} in ${file}; check the file and static HTML.`);
  }
  throw error;
}

When it happens

Trigger: A valid CSS selector that matches nothing in the composition file: wrong file, element absent from static HTML, typo in an id/class, or element only created by JS at runtime.

Common situations: --file pointing at the wrong composition; selector copied from a different scene; target element is injected by client-side JS so it isn't in the static HTML; case mismatch in tag/id/class.

Related errors

• Invalid selector: ${selector}
• Selector matched ${matches.length} elements; use a unique se
• --selector-index ${resolvedIndex} is outside ${matches.lengt
• Color grading requires an <img> or <video>; selector matched
• Cannot merge a grading patch into an unresolved whole-grade

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