{"record":{"id":"7274a60ee064eb75","repo":"paperclipai/paperclip","slug":"acpx-provider-package-manifest-could-not-be-locate","errorCode":null,"errorMessage":"ACPX provider package manifest could not be located for ${packageName}","messagePattern":"ACPX provider package manifest could not be located for (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":382,"sourceCode":"  if (\n    packageSegments.length < 1 ||\n    packageSegments.length > 2 ||\n    packageSegments.some((segment) => segment.length === 0)\n  ) {\n    throw new Error(`ACPX provider package name is invalid: ${packageName}`);\n  }\n  let directory = dirname(realpathSync(issuerRequire.resolve(packageName)));\n  for (let count = 0; count < MAX_DEPENDENCY_ANCESTORS; count += 1) {\n    const matchesPackage =\n      basename(directory) === packageSegments.at(-1) &&\n      (packageSegments.length === 1 ||\n        basename(dirname(directory)) === packageSegments[0]);\n    if (matchesPackage) return resolve(directory, \"package.json\");\n    const parent = dirname(directory);\n    if (parent === directory) break;\n    directory = parent;\n  }\n  throw new Error(\n    `ACPX provider package manifest could not be located for ${packageName}`,\n  );\n}\n\nfunction pathIsInside(root: string, candidate: string): boolean {\n  const candidateRelativePath = relative(root, candidate);\n  return (\n    candidateRelativePath !== \"\" &&\n    candidateRelativePath !== \"..\" &&\n    !candidateRelativePath.startsWith(`..${sep}`) &&\n    !isAbsolute(candidateRelativePath)\n  );\n}\n\nexport interface VerifiedAcpxInstallation {\n  readonly commandDigest: string;\n  readonly agentServerPackageJsonPath: string;\n  readonly agentRuntimePackageJsonPath: string | null;","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L364-L400","documentation":"After the ERR_PACKAGE_PATH_NOT_EXPORTED fallback splits the package name, the function walks up from the resolved module's directory looking for a directory whose basename (and parent, for scoped packages) matches the package segments, then returns its package.json. This error is thrown when no matching directory is found within MAX_DEPENDENCY_ANCESTORS steps before reaching the filesystem root — i.e. the installed module's directory layout does not match the package name.","triggerScenarios":"The package is installed under a directory name that differs from its package name (e.g. pnpm/yarn PnP store paths like node_modules/.pnpm/@scope+pkg@1.2.3/...), the walk exhausts MAX_DEPENDENCY_ANCESTORS, or the resolved entry point lives in a bundle/dist layout that never passes through a directory named after the package.","commonSituations":"pnpm virtual-store layouts where the realpath of the entry escapes the node_modules/<name> directory; packages with a renamed or aliased install directory; deeply nested node_modules exceeding the ancestor cap; packages whose main resolves outside their package directory.","solutions":["Add `\"exports\": { \"./package.json\": \"./package.json\" }` to the target package so issuerRequire.resolve('pkg/package.json') succeeds and this fallback never runs.","Ensure the package is installed with a standard npm/hoisted layout where node_modules/<name>/ contains its own files.","If using pnpm, verify the realpath stays within node_modules and increase/review MAX_DEPENDENCY_ANCESTORS if nesting legitimately exceeds it.","Check that the package's main entry actually resides inside its package directory; fix the package layout if it points elsewhere."],"exampleFix":"// before\n// package.json of dependency lacks exports for ./package.json\n// fallback walk fails in pnpm .pnpm store layout\n// after (in the dependency's package.json)\n\"exports\": {\n  \".\": \"./dist/index.js\",\n  \"./package.json\": \"./package.json\"\n}","handlingStrategy":"try-catch","validationCode":"try {\n  createRequire(issuer).resolve(`${pkg}/package.json`);\n  // fast path OK; resolver will not need the ancestor walk\n} catch (e: any) {\n  if (e?.code === \"ERR_PACKAGE_PATH_NOT_EXPORTED\") {\n    console.warn(`${pkg} lacks a ./package.json export; fallback walk may fail`);\n  }\n}","typeGuard":"null","tryCatchPattern":"try {\n  const manifestPath = resolver(pkg, issuer);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"could not be located\")) {\n    // inspect realpath of require.resolve(pkg) entry and its directory layout;\n    // reinstall the package with a standard node_modules/<name> layout\n  } else throw err;\n}","preventionTips":["Ensure every resolved provider dependency declares an exports entry for './package.json'.","Use standard npm-style installs for the provider root; be cautious with pnpm/PnP layouts that relocate real paths.","Keep dependency nesting shallow and confirm entry points resolve inside their own package directory.","When adding a new qualified dependency, verify resolution once with createRequire(issuer).resolve('<pkg>/package.json')."],"tags":["dependency-resolution","npm","package-exports","filesystem"],"backgroundTag":"resource-not-found","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}