paperclipai/paperclip · error · Error

ACPX provider relative module loading requires Linux descrip

Error message

ACPX provider relative module loading requires Linux descriptor-pinned paths

What it means

Guard around relative module loading used by the ACPX provider setup. Descriptor-pinned (/proc/<pid>/fd/N) paths only work on Linux; on darwin they work only when a private snapshot provides real filesystem paths. If the caller requests a filesystem lookup (filesystemLookup === true) with relative module loading on an unsupported platform combination, this throw prevents resolving modules through paths that cannot exist.

Source

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

    "const metadataAfter = fs.fstatSync(moduleFd, { bigint: true });",
    "verifySnapshotBytes(fileURLToPath(url), moduleSource);",
    `if (moduleSource.length > ${MAX_AGENT_COMMAND_BYTES} || moduleSource.length !== admittedModuleBytes || BigInt(moduleSource.length) !== metadataAfter.size || metadataBefore.dev !== metadataAfter.dev || metadataBefore.ino !== metadataAfter.ino || metadataBefore.size !== metadataAfter.size || metadataBefore.mtimeNs !== metadataAfter.mtimeNs || metadataBefore.ctimeNs !== metadataAfter.ctimeNs) { const error = new Error("ACPX provider module changed while it was read"); error.code = "ERR_ACPX_UNVERIFIED_MODULE"; throw error; }`,
    "return { format: moduleFormat, source: moduleSource, shortCircuit: true };",
    "} finally { fs.closeSync(moduleFd); }",
    "});",
    "} });",
    "import(target).catch((error) => { console.error(error); process.exitCode = 1; });",
  ].join("");
}

export function guardSnapshotModuleLookup<T>(
  platform: NodeJS.Platform,
  filesystemLookup: boolean,
  lookup: () => T,
  privateSnapshot = false,
): T {
  if (platform !== "linux" && !(platform === "darwin" && privateSnapshot) && filesystemLookup) {
    throw new Error(
      "ACPX provider relative module loading requires Linux descriptor-pinned paths",
    );
  }
  return lookup();
}

/** Refuse filesystem modules that are not reached through a retained directory. */
export function guardSnapshotModuleResolution(
  builtin: boolean,
  resolvedUrl: unknown,
  descriptorAuthorized: boolean,
): void {
  if (
    !builtin &&
    typeof resolvedUrl === "string" &&
    resolvedUrl.startsWith("file:") &&
    !descriptorAuthorized
  ) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Run on Linux, where /proc fd-pinned relative module loading is natively supported.
2. On macOS, enable/provision the private snapshot (privateSnapshot = true) so lookups use snapshot paths instead of fd paths.
3. Pass filesystemLookup = false on unsupported platforms to use non-filesystem resolution.
4. Guard platform-specific setup with assertVerifiedAcpxProviderPlatform before attempting lookups.

Example fix

// before
resolveRelativeModule(process.platform, true, () => require(rel));
// after
const fsLookup = process.platform === "linux" || (process.platform === "darwin" && privateSnapshot);
resolveRelativeModule(process.platform, fsLookup, () => require(rel));

const useFsLookup = platform === "linux" || (platform === "darwin" && privateSnapshot);
if (!useFsLookup) {
  // fall back to non-filesystem resolution or fail before attempting lookup
}

When it happens

Trigger: Calling the guarded relative-module lookup helper with platform neither 'linux' nor 'darwin'+privateSnapshot while filesystemLookup is true.

Common situations: Running the ACPX verified provider on macOS without private snapshots enabled; a custom integration forcing filesystemLookup=true; platform-dependent code paths exercised on Windows/other OS during development or tests.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• ACPX provider requires verified package snapshots
• The setup-token login session could not start.
• Pinned OpenCode materialization requires linux/x64, received
• ACPX provider dependency ancestry is invalid
• ACPX provider runtime executable count is invalid

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