{"record":{"id":"7125df4b0ba09966","repo":"heygen-com/hyperframes","slug":"selector-index-resolvedindex-is-outside-mat","errorCode":null,"errorMessage":"--selector-index ${resolvedIndex} is outside ${matches.length} matches","messagePattern":"--selector-index (.+?) is outside (.+?) matches","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":437,"sourceCode":"): { 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\nexport function applyMediaTreatmentToHtml(\n  source: string,\n  options: ApplyMediaTreatmentOptions,\n): ApplyMediaTreatmentResult {\n  const { element, selectorIndex, tag } = selectMediaElement(\n    source,\n    options.selector,\n    options.selectorIndex,\n  );\n  const before = parseStoredGrading(element.getAttribute(HF_COLOR_GRADING_ATTR));","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L419-L455","documentation":"Thrown by selectMediaElement() in packages/cli/src/commands/media-treatment.ts:436. After resolving selectorIndex (default 0), it indexes into the matches array; if that slot is undefined (index >= matches.length), it throws. The reported numbers let you see the actual match count.","triggerScenarios":"Passing `--selector-index N` where N is greater than or equal to the number of elements the selector matched.","commonSituations":"Off-by-one (assuming 1-based or 'last'); assuming there are more matches than there are; copy-pasting an index from a different composition.","solutions":["Use a 0-based index strictly less than the reported match count.","For 'last', first count matches with --dry-run, then pass count-1.","Use a more specific selector so the index isn't needed."],"exampleFix":"# before -- only 2 matches, asked for index 5\nhyperframes media-treatment --selector 'img' --selector-index 5 ...\n# after\nhyperframes media-treatment --selector 'img' --selector-index 1 ...","handlingStrategy":"validation","validationCode":"import { parseHTML } from 'linkedom';\n\nfunction indexInBounds(selector: string, source: string, index: number): boolean {\n  const { document } = parseHTML(source);\n  return index >= 0 && index < document.querySelectorAll(selector).length;\n}","typeGuard":null,"tryCatchPattern":"try {\n  selectMediaElement(source, selector, index);\n} catch (error) {\n  if (/--selector-index .* is outside/.test(String(error))) {\n    // re-query to find the valid range and pick a valid index\n    throw new Error('selector-index out of range; check match count');\n  }\n  throw error;\n}","preventionTips":["Count matches before choosing an index.","Remember indices are 0-based; for 'last' use count-1.","Prefer unique selectors over indices when possible."],"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"}