{"record":{"id":"049132ea71313d3d","repo":"heygen-com/hyperframes","slug":"selector-index-must-be-a-non-negative-integer","errorCode":null,"errorMessage":"--selector-index must be a non-negative integer","messagePattern":"--selector-index must be a non-negative integer","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":474,"sourceCode":"\n  const value = options.clear ? null : serializeGradingPatch(before, options.grading);\n\n  const changed = element.getAttribute(HF_COLOR_GRADING_ATTR) !== value;\n  const after = parseStoredGrading(value);\n  if (!changed) return { html: source, changed: false, tag, value, before, after };\n\n  const patched = patchElementInHtml(source, { selector: options.selector, selectorIndex }, [\n    { type: \"attribute\", property: HF_COLOR_GRADING_ATTR, value },\n  ]);\n  if (!patched.matched) throw new Error(`Could not persist selector: ${options.selector}`);\n  return { html: patched.html, changed: true, tag, value, before, after };\n}\n\nfunction parseSelectorIndex(raw: string | undefined): number | undefined {\n  if (raw === undefined) return undefined;\n  const value = Number(raw);\n  if (!Number.isInteger(value) || value < 0) {\n    throw new Error(\"--selector-index must be a non-negative integer\");\n  }\n  return value;\n}\n\nfunction mediaSourceForElement(element: Element): string {\n  const src =\n    element.getAttribute(\"src\") ??\n    (element.tagName.toLowerCase() === \"video\"\n      ? element.querySelector(\"source\")?.getAttribute(\"src\")\n      : null);\n  if (!src) throw new Error(\"Selected media has no analyzable src\");\n  return src;\n}\n\nexport function resolveMediaTreatmentSource(\n  projectDir: string,\n  compositionFile: string,\n  source: string,","sourceCodeStart":456,"sourceCodeEnd":492,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L456-L492","documentation":"Thrown by parseSelectorIndex() in packages/cli/src/commands/media-treatment.ts:470. It Number()-coerces the raw --selector-index arg and requires Number.isInteger AND value >= 0. Negative, fractional, or non-numeric values all throw.","triggerScenarios":"Passing --selector-index with a negative number (e.g. -1 expecting 'last'), a decimal (e.g. 1.5), or a non-numeric string.","commonSituations":"Assuming -1 means 'last index'; passing a float by mistake; copy-paste artifacts; shell quoting that leaves an empty or malformed value.","solutions":["Use a 0-based non-negative integer (0, 1, 2, ...).","For 'last element', first count matches, then pass count-1.","If you want uniqueness, prefer a more specific selector over an index."],"exampleFix":"# before\nhyperframes media-treatment --selector 'img' --selector-index -1 ...\nhyperframes media-treatment --selector 'img' --selector-index 1.5 ...\n# after\nhyperframes media-treatment --selector 'img' --selector-index 0 ...","handlingStrategy":"validation","validationCode":"function parseSelectorIndex(raw: string | undefined): number | undefined {\n  if (raw === undefined) return undefined;\n  const value = Number(raw);\n  if (!Number.isInteger(value) || value < 0) {\n    throw new Error('--selector-index must be a non-negative integer');\n  }\n  return value;\n}","typeGuard":"function isValidSelectorIndex(raw: string | undefined): raw is `${number}` {\n  if (raw === undefined) return false;\n  const n = Number(raw);\n  return Number.isInteger(n) && n >= 0;\n}","tryCatchPattern":"try {\n  parseSelectorIndex(raw);\n} catch (error) {\n  if (/must be a non-negative integer/.test(String(error))) {\n    // default to 0 or ask the user for a valid index\n    parseSelectorIndex('0');\n  } else throw error;\n}","preventionTips":["Validate --selector-index is a non-negative integer at arg-parse time before invoking the CLI.","Never use -1 to mean 'last'; compute count-1 explicitly.","Reject fractional/empty values upstream in any wrapper script."],"tags":["cli","validation","media-treatment"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}