paperclipai/paperclip · error

ACPX provider dependency ancestry exceeds its bound

Error message

ACPX provider dependency ancestry exceeds its bound

What it means

The verifier builds a bounded list of dependency-ancestor directories (server ancestors, the runtime package directory, and each supplemental claude dependency) that must be opened and monitored for the launch. MAX_DEPENDENCY_ANCESTORS caps this list; exceeding it would mean unbounded trust roots, so verification fails instead of opening an arbitrary number of directories.

Source

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

  }
  for (const supplemental of supplementalPackages) {
    if (
      supplemental.directory !== commandDirectory &&
      !dependencyAncestors.some(
        (ancestor) => ancestor.path === supplemental.directory,
      )
    ) {
      dependencyAncestors.push(
        await inspectExplicitDependencyRoot(
          supplemental.directory,
          `${profile.agent} dependency`,
        ),
      );
      dependencyAncestorFormats.push(supplemental.format);
    }
  }
  if (dependencyAncestors.length > MAX_DEPENDENCY_ANCESTORS) {
    throw new Error("ACPX provider dependency ancestry exceeds its bound");
  }
  const serverDependencyAncestorCount = serverDependencyAncestors.length;

  const commandDigest = command.digest;
  const commandIdentity = command.identity;
  return Object.freeze({
    commandDigest,
    agentServerPackageJsonPath: serverPackageJsonPath,
    agentRuntimePackageJsonPath: runtimePackageJsonPath,
    async openCommand(): Promise<VerifiedAcpxCommandLease> {
      const currentDirectory = await openVerifiedCommandDirectory(
        commandDirectory,
        "provider",
      );
      if (
        !sameDirectoryIdentity(
          currentDirectory.identity,
          commandDirectoryIdentity,

View on GitHub (pinned to 01ad858492)

Solutions

1. Reinstall with a standard hoisted layout (npm ci or pnpm with hoisting) so supplemental dependency directories coincide with the server package's ancestors.
2. Re-run qualification in the same install layout used at runtime so the ancestor count stays within the bound.
3. Increase MAX_DEPENDENCY_ANCESTORS deliberately if the qualified set legitimately needs more roots, and re-verify (treat as a code change, not a workaround).
4. Check realpath output for each dependency: excessive distinct realpaths usually indicate duplicated installs; dedupe node_modules.

Example fix

// before (isolated layout, each dep its own root)
$ pnpm install --node-linker=isolated
// after
$ pnpm install --node-linker=hoisted  # or npm ci, collapsing supplemental dirs into the ancestor chain

// count distinct supplemental roots before verification
const roots = new Set([commandDirectory, ...supplementalDirs]);
if (roots.size > MAX_DEPENDENCY_ANCESTORS) {
  throw new Error(`install layout yields ${roots.size} ancestor roots; expected <= ${MAX_DEPENDENCY_ANCESTORS}`);
}

try {
  await verifyQualifiedAcpxInstallation(input);
} catch (e) {
  if (e.message === "ACPX provider dependency ancestry exceeds its bound") {
    execSync("pnpm install --node-linker=hoisted"); // collapse to standard layout, then re-verify
  } else throw e;
}

When it happens

Trigger: verifyQualifiedAcpxInstallation where, after pushing the runtime directory and every distinct supplemental claude dependency directory not already covered by serverDependencyAncestors or commandDirectory, dependencyAncestors.length exceeds MAX_DEPENDENCY_ANCESTORS — i.e. many supplemental dependencies resolve to distinct directories outside the normal ancestor chain.

Common situations: Deeply nested or unusual install layouts (pnpm symlink farms resolving supplemental packages to many distinct realpaths); a qualified profile expecting a flat node_modules but installed into an isolated per-package layout; qualification-time layout differing from the deployment layout so supplemental dirs no longer coincide with server ancestors.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Qualified ACPX runtime version omitted its package
• ACPX claude package omitted its qualified dependencies
• ACPX claude package dependency mismatch for ${expected.packa
• ACPX claude dependency package version mismatch for ${expect
• ACPX provider runtime executable identity changed after veri

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