paperclipai/paperclip · error · Error

ACPX provider package format is invalid

Error message

ACPX provider package format is invalid

What it means

Child-bootstrap validation of module formats: serverPackageFormat must be exactly "module" or "commonjs", dependencyAncestorFormats must be an array whose length equals dependencyAncestorCount, and every entry must be "module" or "commonjs". This ensures the loader knows the format of every verified ancestor module; anything else would make module resolution ambiguous, so the child aborts.

Source

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

    '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); };",
          'guardian.once("end", reapOnGuardianLoss);',
          'guardian.once("error", reapOnGuardianLoss);',
          "guardian.resume();",
          "fs.fstatSync(guardianFd + 1);",
          "fs.fstatSync(guardianFd + 2);",

View on GitHub (pinned to 01ad858492)

Solutions

1. Spawn via the library's verified spawn() so formats are serialized from the parent's verified arrays with JSON.stringify.
2. Check each ancestor package's declared module format (package.json type / .cjs/.mjs) resolves to module or commonjs only.
3. Confirm the JSON argv entry is passed as a single argument (not split by a shell wrapper).
4. Align package versions so the formats array is generated for the same ancestry the child is told about.

const FORMATS = ["module", "commonjs"];
if (!FORMATS.includes(serverPackageFormat) ||
    !Array.isArray(dependencyAncestorFormats) ||
    dependencyAncestorFormats.length !== dependencyAncestors.length ||
    !dependencyAncestorFormats.every((f) => FORMATS.includes(f))) {
  throw new Error("module formats must resolve to module or commonjs for every ancestor");
}

When it happens

Trigger: Child receives serverPackageFormat outside {module, commonjs}, a non-array dependencyAncestorFormats, an array length mismatched with dependencyAncestorCount, or an element that is neither "module" nor "commonjs".

Common situations: Hand-built argv with formats JSON truncated or wrongly quoted; package.json "type" field producing an unexpected format string; newer/older package versions whose formats array disagrees with the ancestor count; shells or wrappers mangling the JSON argv entry.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• ACPX provider package ancestry is invalid
• The setup-token login session could not start.
• ACPX provider dependency ancestry is invalid
• ACPX provider runtime executable count is invalid
• ACPX verified runtime descriptor is misplaced

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