{"record":{"id":"c53686beb300f7a4","repo":"heygen-com/hyperframes","slug":"media-file-not-found-source","errorCode":null,"errorMessage":"Media file not found: ${source}","messagePattern":"Media file not found: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/media-treatment.ts","lineNumber":507,"sourceCode":"export function resolveMediaTreatmentSource(\n  projectDir: string,\n  compositionFile: string,\n  source: string,\n): string {\n  const sourceUrl = source.trim();\n  if (!sourceUrl) throw new Error(\"Selected media has no analyzable local src\");\n  if (isRemoteOrInlineUrl(sourceUrl)) {\n    throw new Error(\n      \"Media analysis requires a local project asset; freeze remote media with media-use first\",\n    );\n  }\n  const cleanSource = cleanAssetUrl(sourceUrl);\n  if (!cleanSource) throw new Error(\"Selected media has no analyzable local src\");\n  const projectRelative = cleanSource.startsWith(\"/\")\n    ? cleanSource\n    : rewriteAssetPath(compositionFile, cleanSource, (path) => existsSync(join(projectDir, path)));\n  const asset = resolveExistingLocalAsset(projectDir, projectRelative);\n  if (!asset) throw new Error(`Media file not found: ${source}`);\n  return asset.resolved;\n}\n\nfunction parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {\n  if (clear) {\n    if (raw !== undefined || apply) {\n      throw new Error(\"Use either --apply with --grading or --clear, not both\");\n    }\n    return undefined;\n  }\n  if (!apply) {\n    if (raw !== undefined) throw new Error(\"--grading requires --apply\");\n    throw new Error(\"Use --apply with --grading <json> or --clear\");\n  }\n  if (raw === undefined) throw new Error(\"--apply requires --grading <json>\");\n  try {\n    return JSON.parse(raw);\n  } catch (error) {","sourceCodeStart":489,"sourceCodeEnd":525,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/media-treatment.ts#L489-L525","documentation":"Thrown by resolveMediaTreatmentSource after resolveExistingLocalAsset returned null — the src was local and non-empty, but no file exists at the resolved path on disk. The CLI rewrites relative paths against the composition file location and checks existence; when nothing matches, the asset is considered missing.","triggerScenarios":"The matched element's src references a path like \"media/hero.jpg\" but the file lives at \"assets/hero.jpg\". The asset was deleted, moved, or never committed. The composition file is in a subdirectory and the relative path is resolved from the wrong base.","commonSituations":"Asset directory renames without updating composition HTML. Cross-platform path separators. Assets excluded by .gitignore that weren't pulled locally. Compositions copied between projects without their asset folders.","solutions":["Verify the actual file location with `ls` and correct the src attribute to match","If the file was moved, update the src path in the composition HTML","Ensure the asset is present on disk (not gitignored-away) before running --analyze","Check that the relative path is correct relative to the composition file's directory, not the project root"],"exampleFix":"// before — file is at assets/hero.jpg but src says media/\n<img src=\"media/hero.jpg\" id=\"hero\">\n// after\n<img src=\"assets/hero.jpg\" id=\"hero\">","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\n\nfunction assetExistsOnDisk(projectDir: string, relativePath: string): boolean {\n  return existsSync(join(projectDir, relativePath));\n}\n// check before calling resolveMediaTreatmentSource\nif (!assetExistsOnDisk(projectDir, cleanSource)) {\n  throw new Error(`Asset missing on disk: ${cleanSource}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  const resolved = resolveMediaTreatmentSource(projectDir, compFile, source);\n} catch (e) {\n  if (e instanceof Error && /Media file not found/.test(e.message)) {\n    // prompt user/agent to correct or download the asset\n  } else throw e;\n}","preventionTips":["Validate asset paths exist after any rename or move","Commit assets alongside composition HTML to avoid missing-file drift"],"tags":["media-treatment","file-not-found","asset-path","cli"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}