{"record":{"id":"1c3015cedc9e2694","repo":"heygen-com/hyperframes","slug":"composition-file-not-found-filearg","errorCode":null,"errorMessage":"Composition file not found: ${fileArg}","messagePattern":"Composition file not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":579,"sourceCode":"  ].some(Boolean);\n  if (hasMutationOption) throw new Error(\"--capabilities cannot be combined with mutation options\");\n  if (args.all === true && capability)\n    throw new Error(\"Use either --all or --capability, not both\");\n\n  let capabilities: unknown = getMediaTreatmentCapabilityOverview();\n  if (args.all === true) capabilities = getHfColorGradingCapabilities();\n  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\"),","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L561-L597","documentation":"Thrown by resolveMutationFile when the --file path passes the inside-project and .html checks but does not exist on disk (existsSync returns false). The file argument (as written by the user, not the resolved path) is echoed in the message.","triggerScenarios":"Passing `--file missing.html` or `--file compositions/old-name.html` where the file was renamed or never created. Defaulting to index.html when the project uses a different entry name.","commonSituations":"Renamed composition files. Wrong default assumption (project uses scene.html not index.html). Typo in the filename. File exists in a different subdirectory.","solutions":["List the project directory to find the correct HTML file name","Use the actual entry file: `--file <correct-name>.html`","If using the default, ensure index.html exists or pass the real entry explicitly","Create the composition file if it should exist"],"exampleFix":"// before\nhyperframes media-treatment --file missing.html --selector '#hero' --apply\n// after — use the file that exists\nhyperframes media-treatment --file index.html --selector '#hero' --apply","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\n\nfunction assertCompositionExists(projectDir: string, fileArg: string): void {\n  if (!existsSync(resolve(projectDir, fileArg))) {\n    throw new Error(`Composition file not found: ${fileArg}`);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["List the project directory to confirm the entry file name before running","Pass --file explicitly rather than relying on the index.html default"],"tags":["media-treatment","cli","file-not-found","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}