What causes "${entryFile} not found in project directory" in heygen-com/hyperframes?

Verify the file exists at the expected absolute path: ls / .

heygen-com/hyperframes · error · Error

${entryFile} not found in project directory

Error message

${entryFile} not found in project directory

What it means

Thrown by bundleToSingleHtml when the entry HTML file (default 'index.html', overridable via options.entryFile) cannot be resolved inside projectDir. Resolution uses resolveWithinProject which both confines the path to the project directory (rejecting '../' traversal) and checks existence with existsSync — failure of either guard trips the throw. This is the bundler's front-door precondition: no entry file, nothing to inline.

Source

Thrown at packages/core/src/compiler/htmlBundler.ts:793

            )
          : wrapInlineScriptWithErrorBoundary(
              scriptEl.textContent || "",
              "[HyperFrames] composition script error:",
            ),
      );
    }
    scriptEl.remove();
  }
}

export async function bundleToSingleHtml(
  projectDir: string,
  options?: BundleOptions,
): Promise<string> {
  const entryFile = options?.entryFile ?? "index.html";
  const indexPath = resolveWithinProject(projectDir, entryFile);
  if (!indexPath || !existsSync(indexPath)) {
    throw new Error(`${entryFile} not found in project directory`);
  }
  const sourceDir = dirname(indexPath);
  const resolveEntryPath = (relativePath: string): string | null => {
    const resolved = resolve(sourceDir, relativePath);
    return isSafePath(projectDir, resolved) ? resolved : null;
  };

  const rawHtml = readFileSync(indexPath, "utf-8");
  const compiled = await compileHtml(rawHtml, sourceDir, options?.probeMediaDuration);

  const staticGuard = await validateHyperframeHtmlContract(compiled);
  if (!staticGuard.isValid) {
    console.warn(
      `[StaticGuard] Invalid HyperFrame contract: ${staticGuard.missingKeys.join("; ")}`,
    );
  }

  const withInterceptor = injectInterceptor(compiled, options?.runtime ?? "inline");

View on GitHub (pinned to c2996c8626)

Solutions

Verify the file exists at the expected absolute path: ls <projectDir>/<entryFile>.
Confirm you are invoking the bundler with the correct projectDir (absolute paths are safest).
Check options.entryFile spelling and casing against the actual file on disk.
If you meant a non-default entry, pass it explicitly: bundleToSingleHtml(dir, { entryFile: 'home.html' }).

Example fix

// before — wrong cwd makes relative projectDir miss
await bundleToSingleHtml('./myproj');

// after — absolute path removes cwd ambiguity
await bundleToSingleHtml(resolve(process.cwd(), 'myproj'));

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
import { resolve, isAbsolute } from 'node:path';
export function assertEntryExists(projectDir: string, entryFile = 'index.html'): string {
  const abs = isAbsolute(entryFile) ? entryFile : resolve(projectDir, entryFile);
  if (!existsSync(abs)) throw new Error(`entry not found: ${abs}`);
  return abs;
}
// call before bundleToSingleHtml
assertEntryExists(projectDir, options?.entryFile);

Try / catch

try {
  await bundleToSingleHtml(projectDir, options);
} catch (err) {
  if (err instanceof Error && /not found in project directory/.test(err.message)) {
    console.error(`Cannot find entry file. cwd=${process.cwd()}`);
  } else throw err;
}

Prevention

Always pass an absolute projectDir to bundleToSingleHtml to remove cwd ambiguity.
In CLI wrappers, validate the entry file exists before invoking the bundler and emit a clearer message.
Treat entryFile as case-sensitive even on case-insensitive OSes for portability.

When it happens

Trigger: Calling bundleToSingleHtml('/wrong/path') where the directory has no index.html; passing options.entryFile='home.html' when only index.html exists; passing entryFile='../../etc/passwd' (resolveWithinProject returns null on traversal); running the CLI from a different cwd than the project root so the relative projectDir resolves to the wrong place.

Common situations: Wrong cwd when invoking the CLI (projectDir is relative and resolves against the shell's cwd); typo'd entry file name; the file exists but with different casing on a case-sensitive filesystem; entryFile passed with a leading slash making it absolute and outside projectDir; fresh scaffold where index.html was never created.

Related errors

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