{"record":{"id":"38a2fbd0c08c2a5f","repo":"heygen-com/hyperframes","slug":"selector-is-required","errorCode":null,"errorMessage":"--selector is required","messagePattern":"--selector is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":586,"sourceCode":"  else if (capability) capabilities = getMediaTreatmentCapabilityDetail(capability);\n  console.log(JSON.stringify(withMeta({ ok: true, capabilities }), null, 2));\n}\n\nfunction resolveMutationFile(args: MediaTreatmentCommandArgs) {\n  const project = resolveProject(readOptionalString(args.project));\n  const fileArg = readOptionalString(args.file) ?? \"index.html\";\n  const filePath = resolve(project.dir, fileArg);\n  if (!isPathInside(filePath, project.dir) || !filePath.toLowerCase().endsWith(\".html\")) {\n    throw new Error(\"--file must be an HTML file inside the project\");\n  }\n  if (!existsSync(filePath)) throw new Error(`Composition file not found: ${fileArg}`);\n  return { project, filePath };\n}\n\nfunction analyzeTarget(args: MediaTreatmentCommandArgs) {\n  const { project, filePath } = resolveMutationFile(args);\n  const selector = readOptionalString(args.selector);\n  if (!selector) throw new Error(\"--selector is required\");\n  if (\n    readOptionalString(args.grading) ||\n    args.clear === true ||\n    args.apply === true ||\n    args[\"dry-run\"] === true\n  ) {\n    throw new Error(\"--analyze cannot be combined with mutation options\");\n  }\n  const selectorIndex = parseSelectorIndex(readOptionalString(args[\"selector-index\"]));\n  const { element, tag } = selectMediaElement(\n    readFileSync(filePath, \"utf8\"),\n    selector,\n    selectorIndex,\n  );\n  const source = mediaSourceForElement(element);\n  const compositionFile = relative(project.dir, filePath).split(\"\\\\\").join(\"/\");\n  const mediaPath = resolveMediaTreatmentSource(project.dir, compositionFile, source);\n  return {","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L568-L604","documentation":"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.","triggerScenarios":"Running `hyperframes media-treatment --analyze` or `hyperframes media-treatment --analyze --json` with no --selector argument.","commonSituations":"Agents that assume --analyze inspects all media. Users who forget the selector when switching from --capabilities to --analyze.","solutions":["Add a CSS selector targeting one <img> or <video>: `--selector '#hero' --analyze`","Use --selector-index if the selector matches multiple elements","Inspect the composition HTML to find a unique selector for the media element"],"exampleFix":"// before\nhyperframes media-treatment --analyze\n// after\nhyperframes media-treatment --selector '#hero' --analyze","handlingStrategy":"validation","validationCode":"function requireSelectorForAnalyze(selector?: string): void {\n  if (!selector) throw new Error('--selector is required for --analyze');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair --analyze with a unique --selector","Inspect the composition to find a valid selector first"],"tags":["media-treatment","cli","missing-flag","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}