heygen-com/hyperframes · error · Error

Media file not found: ${source}

Error message

Media file not found: ${source}

What it means

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.

Source

Thrown at packages/cli/src/commands/media-treatment.ts:507

export function resolveMediaTreatmentSource(
  projectDir: string,
  compositionFile: string,
  source: string,
): string {
  const sourceUrl = source.trim();
  if (!sourceUrl) throw new Error("Selected media has no analyzable local src");
  if (isRemoteOrInlineUrl(sourceUrl)) {
    throw new Error(
      "Media analysis requires a local project asset; freeze remote media with media-use first",
    );
  }
  const cleanSource = cleanAssetUrl(sourceUrl);
  if (!cleanSource) throw new Error("Selected media has no analyzable local src");
  const projectRelative = cleanSource.startsWith("/")
    ? cleanSource
    : rewriteAssetPath(compositionFile, cleanSource, (path) => existsSync(join(projectDir, path)));
  const asset = resolveExistingLocalAsset(projectDir, projectRelative);
  if (!asset) throw new Error(`Media file not found: ${source}`);
  return asset.resolved;
}

function parseGrading(raw: string | undefined, apply: boolean, clear: boolean): unknown {
  if (clear) {
    if (raw !== undefined || apply) {
      throw new Error("Use either --apply with --grading or --clear, not both");
    }
    return undefined;
  }
  if (!apply) {
    if (raw !== undefined) throw new Error("--grading requires --apply");
    throw new Error("Use --apply with --grading <json> or --clear");
  }
  if (raw === undefined) throw new Error("--apply requires --grading <json>");
  try {
    return JSON.parse(raw);
  } catch (error) {

View on GitHub (pinned to c2996c8626)

Solutions

1. Verify the actual file location with `ls` and correct the src attribute to match
2. If the file was moved, update the src path in the composition HTML
3. Ensure the asset is present on disk (not gitignored-away) before running --analyze
4. Check that the relative path is correct relative to the composition file's directory, not the project root

Example fix

// before — file is at assets/hero.jpg but src says media/
<img src="media/hero.jpg" id="hero">
// after
<img src="assets/hero.jpg" id="hero">

import { existsSync } from 'node:fs';
import { join } from 'node:path';

function assetExistsOnDisk(projectDir: string, relativePath: string): boolean {
  return existsSync(join(projectDir, relativePath));
}
// check before calling resolveMediaTreatmentSource
if (!assetExistsOnDisk(projectDir, cleanSource)) {
  throw new Error(`Asset missing on disk: ${cleanSource}`);
}

try {
  const resolved = resolveMediaTreatmentSource(projectDir, compFile, source);
} catch (e) {
  if (e instanceof Error && /Media file not found/.test(e.message)) {
    // prompt user/agent to correct or download the asset
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Composition file not found: ${fileArg}
• --selector-index must be a non-negative integer
• Media analysis requires a local project asset; freeze remote
• Use either --apply with --grading or --clear, not both
• --grading requires --apply

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/c53686beb300f7a4. Report an issue: GitHub.