{"record":{"id":"43241160d8101e64","repo":"heygen-com/hyperframes","slug":"entryfile-not-found-in-project-directory","errorCode":null,"errorMessage":"${entryFile} not found in project directory","messagePattern":"(.+?) not found in project directory","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/compiler/htmlBundler.ts","lineNumber":793,"sourceCode":"            )\n          : wrapInlineScriptWithErrorBoundary(\n              scriptEl.textContent || \"\",\n              \"[HyperFrames] composition script error:\",\n            ),\n      );\n    }\n    scriptEl.remove();\n  }\n}\n\nexport async function bundleToSingleHtml(\n  projectDir: string,\n  options?: BundleOptions,\n): Promise<string> {\n  const entryFile = options?.entryFile ?? \"index.html\";\n  const indexPath = resolveWithinProject(projectDir, entryFile);\n  if (!indexPath || !existsSync(indexPath)) {\n    throw new Error(`${entryFile} not found in project directory`);\n  }\n  const sourceDir = dirname(indexPath);\n  const resolveEntryPath = (relativePath: string): string | null => {\n    const resolved = resolve(sourceDir, relativePath);\n    return isSafePath(projectDir, resolved) ? resolved : null;\n  };\n\n  const rawHtml = readFileSync(indexPath, \"utf-8\");\n  const compiled = await compileHtml(rawHtml, sourceDir, options?.probeMediaDuration);\n\n  const staticGuard = await validateHyperframeHtmlContract(compiled);\n  if (!staticGuard.isValid) {\n    console.warn(\n      `[StaticGuard] Invalid HyperFrame contract: ${staticGuard.missingKeys.join(\"; \")}`,\n    );\n  }\n\n  const withInterceptor = injectInterceptor(compiled, options?.runtime ?? \"inline\");","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/core/src/compiler/htmlBundler.ts#L775-L811","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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' })."],"exampleFix":"// before — wrong cwd makes relative projectDir miss\nawait bundleToSingleHtml('./myproj');\n\n// after — absolute path removes cwd ambiguity\nawait bundleToSingleHtml(resolve(process.cwd(), 'myproj'));","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { resolve, isAbsolute } from 'node:path';\nexport function assertEntryExists(projectDir: string, entryFile = 'index.html'): string {\n  const abs = isAbsolute(entryFile) ? entryFile : resolve(projectDir, entryFile);\n  if (!existsSync(abs)) throw new Error(`entry not found: ${abs}`);\n  return abs;\n}\n// call before bundleToSingleHtml\nassertEntryExists(projectDir, options?.entryFile);","typeGuard":null,"tryCatchPattern":"try {\n  await bundleToSingleHtml(projectDir, options);\n} catch (err) {\n  if (err instanceof Error && /not found in project directory/.test(err.message)) {\n    console.error(`Cannot find entry file. cwd=${process.cwd()}`);\n  } else throw err;\n}","preventionTips":["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."],"tags":["bundler","html","filesystem","path-traversal"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}