paperclipai/paperclip · error

ACPX runtime snapshot digest mismatch

Error message

ACPX runtime snapshot digest mismatch

What it means

After snapshotting on macOS, if the qualified runtime executable was snapshotted, its sha256 digest inside the private snapshot is compared with the digest recorded at verification time. A mismatch means the copied executable in the snapshot differs from the verified binary (corrupt or partially written copy), so the launch is aborted rather than executing an unverified copy.

Source

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

        }
        const privateSnapshot = process.platform === "darwin"
          ? await createAcpxPrivateSnapshot([commandDirectory, ...dependencyAncestors.map((root) => root.path)], currentRuntimeExecutable)
          : null;
        if (privateSnapshot) {
          try {
            // Bind copied trees to the identities retained by the verified lease.
            const paths = [commandDirectory, ...dependencyAncestors.map((root) => root.path)];
            const handles = [currentDirectory.handle, ...currentDependencyAncestors];
            for (let index = 0; index < paths.length; index++) {
              const lexical = await lstat(paths[index]!, { bigint: true });
              const held = await handles[index]!.stat({ bigint: true });
              if (lexical.isSymbolicLink() || !sameIdentity(fileIdentity(lexical), fileIdentity(held))) {
                throw new Error("ACPX package directory changed while snapshotting");
              }
            }
            if (runtimeExecutable && privateSnapshot.executable &&
              `sha256:${privateSnapshot.digests[privateSnapshot.executable]}` !== runtimeExecutable.digest) {
              throw new Error("ACPX runtime snapshot digest mismatch");
            }
          } catch (error) { await privateSnapshot.close(); throw error; }
        }
        return commandLease(
          commandDirectory,
          basename(commandPath),
          commandFormat,
          current.bytes,
          currentDirectory.handle,
          currentDependencyAncestors,
          serverDependencyAncestorCount,
          serverPackageFormat,
          dependencyAncestorFormats,
          currentRuntimeExecutable,
          runtimeExecutable?.environmentVariable ?? null,
          privateSnapshot,
        );
      } catch (error) {

View on GitHub (pinned to 01ad858492)

Solutions

1. Retry openCommand — transient copy failures (disk pressure, concurrent write) often resolve on a clean re-snapshot after re-verification.
2. Check free disk space and filesystem health (fsck/Disk Utility) on the volume holding the install.
3. Re-verify and re-open with no concurrent writers; confirm the source binary still hashes to the qualified digest.
4. If persistent, reinstall the qualified runtime package and re-run installation verification.

Example fix

// before
const lease = await verified.openCommand(); // snapshot copy truncated by full disk
// after
await ensureDiskSpace(minBytes);              // free space before snapshot
const lease = await reverified.openCommand();

const free = await checkDiskSpace(path.dirname(runtimeExecutable.path));
if (free < minRequiredBytes) throw new Error(`insufficient disk for private snapshot: ${free} free`);

try {
  lease = await verified.openCommand();
} catch (e) {
  if (e.message === "ACPX runtime snapshot digest mismatch") {
    await reclaimDiskSpace();
    verified = await verifyQualifiedAcpxInstallation(input);
    lease = await verified.openCommand(); // retry after clean environment
  } else throw e;
}

When it happens

Trigger: openCommand on darwin where runtimeExecutable and privateSnapshot.executable are both set but `sha256:${privateSnapshot.digests[privateSnapshot.executable]}` !== runtimeExecutable.digest — the snapshot copy's hash differs from the qualified runtime digest.

Common situations: Disk-full or I/O error during the snapshot copy truncating the executable; the source file being replaced mid-copy (usually preceded by error 216); flaky storage or filesystem corruption; a security tool modifying the file during read.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• ACPX package directory changed while snapshotting
• 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

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