paperclipai/paperclip · error · Error

ACPX provider requires verified package snapshots

Error message

ACPX provider requires verified package snapshots

What it means

Thrown by the generated provider bootstrap in the child process. On Linux the provider is allowed to run from descriptor-pinned paths without a private snapshot, but on any other platform (notably macOS) it must be handed a verified private snapshot whose roots array has exactly dependencyAncestorCount + 1 entries. If neither condition holds, the child refuses to start because the provider would load unverified package code.

Source

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

function snapshotBootstrap(format: AcpxCommandFormat, guarded = false): string {
  return [
    'const fs = require("node:fs");',
    'const { isBuiltin, registerHooks } = require("node:module");',
    'const { dirname, extname, join, normalize, relative, resolve } = require("node:path");',
    'const { fileURLToPath, pathToFileURL } = require("node:url");',
    "const commandDirectory = process.argv[1];",
    "const commandName = process.argv[2];",
    "const dependencyAncestorCount = Number.parseInt(process.argv[3], 10);",
    "const serverDependencyAncestorCount = Number.parseInt(process.argv[4], 10);",
    "const serverPackageFormat = process.argv[5];",
    "const dependencyAncestorFormats = JSON.parse(process.argv[6]);",
    "const providerRuntimeExecutableCount = Number.parseInt(process.argv[7], 10);",
    `const providerRuntimeEnvironmentVariable = process.env.${VERIFIED_PROVIDER_RUNTIME_TARGET_ENV};`,
    `delete process.env.${VERIFIED_PROVIDER_RUNTIME_TARGET_ENV};`,
    `const snapshotHandoff = process.platform === "darwin" ? JSON.parse(process.env.${ACPX_PRIVATE_SNAPSHOT_ENV} || "null") : null;`,
    'let privateSnapshot = null; if (snapshotHandoff) { const manifest = fs.readFileSync(snapshotHandoff.path); if (require("node:crypto").createHash("sha256").update(manifest).digest("hex") !== snapshotHandoff.digest) throw new Error("ACPX snapshot manifest digest mismatch"); privateSnapshot = JSON.parse(manifest); }',
    `delete process.env.${ACPX_PRIVATE_SNAPSHOT_ENV};`,
    'if (process.platform !== "linux" && !(process.platform === "darwin" && privateSnapshot && Array.isArray(privateSnapshot.roots) && privateSnapshot.roots.length === dependencyAncestorCount + 1)) throw new Error("ACPX provider requires verified package snapshots");',
    'const verifySnapshotBytes = (path, bytes) => { if (privateSnapshot && require("node:crypto").createHash("sha256").update(bytes).digest("hex") !== privateSnapshot.digests[path]) throw new Error("ACPX private snapshot digest mismatch"); };',
    'if (privateSnapshot && providerRuntimeExecutableCount === 1) verifySnapshotBytes(privateSnapshot.executable, fs.readFileSync(privateSnapshot.executable));',
    `if (!Number.isSafeInteger(dependencyAncestorCount) || dependencyAncestorCount < 0 || dependencyAncestorCount > ${MAX_DEPENDENCY_ANCESTORS}) throw new Error("ACPX provider dependency ancestry is invalid");`,
    'if (!Number.isSafeInteger(serverDependencyAncestorCount) || serverDependencyAncestorCount < 0 || serverDependencyAncestorCount > dependencyAncestorCount) throw new Error("ACPX provider package ancestry is invalid");',
    'if ((serverPackageFormat !== "module" && serverPackageFormat !== "commonjs") || !Array.isArray(dependencyAncestorFormats) || dependencyAncestorFormats.length !== dependencyAncestorCount || dependencyAncestorFormats.some((value) => value !== "module" && value !== "commonjs")) throw new Error("ACPX provider package formats are invalid");',
    'if (providerRuntimeExecutableCount !== 0 && providerRuntimeExecutableCount !== 1) throw new Error("ACPX provider runtime executable count is invalid");',
    `const providerRuntimeExecutableFd = ${DEPENDENCY_ANCESTOR_FD_START} + dependencyAncestorCount;`,
    'if (providerRuntimeExecutableCount === 1) { if (providerRuntimeEnvironmentVariable !== "CODEX_PATH" && providerRuntimeEnvironmentVariable !== "CLAUDE_CODE_EXECUTABLE") throw new Error("ACPX provider runtime environment target is invalid"); fs.fstatSync(providerRuntimeExecutableFd); process.env[providerRuntimeEnvironmentVariable] = privateSnapshot ? privateSnapshot.executable : "/proc/" + process.pid + "/fd/" + providerRuntimeExecutableFd; } else if (providerRuntimeEnvironmentVariable !== undefined) throw new Error("ACPX provider runtime environment target is unexpected");',
    ...(guarded
      ? [
          `const guardianFd = ${DEPENDENCY_ANCESTOR_FD_START} + dependencyAncestorCount + providerRuntimeExecutableCount;`,
          'const guardian = fs.createReadStream("", { fd: guardianFd, autoClose: false });',
          `const reapCurrentProviderProcessGroup = ${reapCurrentProviderProcessGroup.toString()};`,
          "const killProviderProcess = process.kill.bind(process);",
          "const providerProcessId = process.pid;",
          "const exitProviderProcess = process.exit.bind(process);",
          "let guardianLost = false;",
          "const reapOnGuardianLoss = () => { if (guardianLost) return; guardianLost = true; reapCurrentProviderProcessGroup(killProviderProcess, providerProcessId, exitProviderProcess); };",

View on GitHub (pinned to 01ad858492)

Solutions

1. Run the guarded provider on Linux (fully supported without private snapshots) or on macOS with the private snapshot correctly provisioned.
2. Verify ACPX_PRIVATE_SNAPSHOT_ENV is present in the child environment and not removed by env sanitization in spawn options.
3. Rebuild the private snapshot so its roots match the current dependencyAncestorCount (+1 for the server root).
4. If spawning manually with a custom env, preserve the snapshot handoff variables rather than passing a minimal env.

const snapshotSupported = process.platform === "linux" || (process.platform === "darwin" && privateSnapshot?.roots?.length === dependencyAncestors.length + 1);
if (!snapshotSupported) throw new Error("provision a private snapshot or run on Linux before spawning the guarded provider");

const hasValidSnapshot = (s): s is PrivateSnapshot =>
  !!s && Array.isArray(s.roots) && s.roots.length > 0;

When it happens

Trigger: Spawning the guarded ACPX provider with process.platform neither 'linux' nor darwin-with-a-valid-privateSnapshot (null handoff, non-array roots, or roots.length !== dependencyAncestorCount + 1).

Common situations: Running the runner on macOS without the darwin private-snapshot path set up; the snapshot handoff env var was stripped (e.g. by a sanitized environment) before the child started; dependency ancestor count changed after the snapshot was built.

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 snapshot manifest digest mismatch
• ACPX private snapshot digest mismatch
• Materialized OpenCode executable digest mismatch
• Public viewer asset differs from trusted build: ${file}
• ACPX ${agent} runtime executable digest mismatch

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