{"record":{"id":"36eac30e42494b2f","repo":"heygen-com/hyperframes","slug":"selector-did-not-match-selector","errorCode":null,"errorMessage":"Selector did not match: ${selector}","messagePattern":"Selector did not match: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":427,"sourceCode":"    const nested = queryIncludingTemplates(template, selector);\n    if (nested.length > 0) return nested;\n  }\n  return [];\n}\n\nfunction selectMediaElement(\n  source: string,\n  selector: string,\n  selectorIndex?: number,\n): { element: Element; selectorIndex: number; tag: \"img\" | \"video\" } {\n  const document = parseSourceDocument(source);\n  let matches: Element[];\n  try {\n    matches = queryIncludingTemplates(document, selector);\n  } catch {\n    throw new Error(`Invalid selector: ${selector}`);\n  }\n  if (matches.length === 0) throw new Error(`Selector did not match: ${selector}`);\n  if (selectorIndex === undefined && matches.length > 1) {\n    throw new Error(\n      `Selector matched ${matches.length} elements; use a unique selector or --selector-index`,\n    );\n  }\n\n  const resolvedIndex = selectorIndex ?? 0;\n  const element = matches[resolvedIndex];\n  if (!element) {\n    throw new Error(`--selector-index ${resolvedIndex} is outside ${matches.length} matches`);\n  }\n  const tag = element.tagName.toLowerCase();\n  if (tag !== \"img\" && tag !== \"video\") {\n    throw new Error(`Color grading requires an <img> or <video>; selector matched <${tag}>`);\n  }\n  return { element, selectorIndex: resolvedIndex, tag };\n}\n","sourceCodeStart":409,"sourceCodeEnd":445,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L409-L445","documentation":"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).","triggerScenarios":"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.","commonSituations":"--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.","solutions":["Open the exact --file and search for the selector string to confirm it's present in static HTML.","If the element is JS-generated, point at the source template/HTML where it's authored, not a runtime snapshot.","Broaden the selector (e.g. 'img' instead of '#hero-img') to confirm any match exists, then narrow.","Verify the --file path is relative to the project dir and ends in .html."],"exampleFix":"# before\nhyperframes media-treatment --file scenes/old.html --selector '#hero' ...\n# after -- correct file\nhyperframes media-treatment --file scenes/scene.html --selector '#hero' ...","handlingStrategy":"validation","validationCode":"import { parseHTML } from 'linkedom';\n\nfunction selectorMatchesInSource(selector: string, source: string): boolean {\n  const { document } = parseHTML(source);\n  return document.querySelectorAll(selector).length > 0;\n}","typeGuard":null,"tryCatchPattern":"try {\n  selectMediaElement(source, selector);\n} catch (error) {\n  if (/Selector did not match/.test(String(error))) {\n    // verify the --file path and that the element exists in static HTML\n    throw new Error(`No match for ${selector} in ${file}; check the file and static HTML.`);\n  }\n  throw error;\n}","preventionTips":["Confirm the element exists in static HTML (not JS-generated) before targeting it.","Verify the --file path is the composition that actually contains the element.","Broaden the selector to confirm any match, then narrow."],"tags":["css","validation","media-treatment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}