ACPX provider package manifest could not be located for ${pa

Error message

ACPX provider package manifest could not be located for ${packageName}

What it means

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.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts:382

  if (
    packageSegments.length < 1 ||
    packageSegments.length > 2 ||
    packageSegments.some((segment) => segment.length === 0)
  ) {
    throw new Error(`ACPX provider package name is invalid: ${packageName}`);
  }
  let directory = dirname(realpathSync(issuerRequire.resolve(packageName)));
  for (let count = 0; count < MAX_DEPENDENCY_ANCESTORS; count += 1) {
    const matchesPackage =
      basename(directory) === packageSegments.at(-1) &&
      (packageSegments.length === 1 ||
        basename(dirname(directory)) === packageSegments[0]);
    if (matchesPackage) return resolve(directory, "package.json");
    const parent = dirname(directory);
    if (parent === directory) break;
    directory = parent;
  }
  throw new Error(
    `ACPX provider package manifest could not be located for ${packageName}`,
  );
}

function pathIsInside(root: string, candidate: string): boolean {
  const candidateRelativePath = relative(root, candidate);
  return (
    candidateRelativePath !== "" &&
    candidateRelativePath !== ".." &&
    !candidateRelativePath.startsWith(`..${sep}`) &&
    !isAbsolute(candidateRelativePath)
  );
}

export interface VerifiedAcpxInstallation {
  readonly commandDigest: string;
  readonly agentServerPackageJsonPath: string;
  readonly agentRuntimePackageJsonPath: string | null;

View on GitHub (pinned to 01ad858492)

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.

Example fix

// before
// package.json of dependency lacks exports for ./package.json
// fallback walk fails in pnpm .pnpm store layout
// after (in the dependency's package.json)
"exports": {
  ".": "./dist/index.js",
  "./package.json": "./package.json"
}

Defensive patterns

Strategy: try-catch

Validate before calling

try {
  createRequire(issuer).resolve(`${pkg}/package.json`);
  // fast path OK; resolver will not need the ancestor walk
} catch (e: any) {
  if (e?.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
    console.warn(`${pkg} lacks a ./package.json export; fallback walk may fail`);
  }
}

Type guard

null

Try / catch

try {
  const manifestPath = resolver(pkg, issuer);
} catch (err) {
  if (err instanceof Error && err.message.includes("could not be located")) {
    // inspect realpath of require.resolve(pkg) entry and its directory layout;
    // reinstall the package with a standard node_modules/<name> layout
  } else throw err;
}

Prevention

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').

When it happens

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

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

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/7274a60ee064eb75. Report an issue: GitHub.