paperclipai/paperclip · error · Error

ACPX snapshot exceeds its byte bound

Error message

ACPX snapshot exceeds its byte bound

What it means

createAcpxPrivateSnapshot builds a private snapshot of the ACPX runtime executable(s) and enforces a cumulative byte budget (MAX_SNAPSHOT_BYTES). This error is thrown when the running total of copied executable bytes exceeds that bound, before allocating or writing the file. It exists so a pathological or unexpectedly huge runtime binary cannot cause unbounded disk usage or allocation during snapshotting.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts:195

        // Include generated directories in cleanup and read-only sealing.
        directories.push(join(root, "node_modules"), dirname(target));
        await symlink(pkg.root, target).catch(
          (error: NodeJS.ErrnoException) => {
            if (error.code !== "EEXIST") throw error;
          },
        );
      }
    let executablePath: string | null = null;
    if (executable) {
      const before = await executable.stat({ bigint: true });
      if (!before.isFile() || before.size < 1n || before.size > BigInt(MAX_ACPX_RUNTIME_EXECUTABLE_BYTES)) {
        throw new Error("ACPX runtime executable must be a bounded executable file");
      }
      // The bigint bound above makes this conversion exact before allocation.
      const executableBytes = Number(before.size);
      bytesCopied += executableBytes;
      if (bytesCopied > MAX_SNAPSHOT_BYTES) {
        throw new Error("ACPX snapshot exceeds its byte bound");
      }
      const bytes = await readSnapshotBytes(executable, executableBytes);
      if (!same(before, await executable.stat({ bigint: true })))
        throw new Error("ACPX executable changed during snapshot");
      executablePath = join(directory, "runtime");
      await writeFile(executablePath, bytes, { flag: "wx", mode: 0o500 });
      digests[executablePath] = digest(bytes);
    }
    const manifest = Buffer.from(
      JSON.stringify({ roots, executable: executablePath, digests }),
    );
    const manifestPath = join(directory, "manifest.json");
    await writeFile(manifestPath, manifest, { flag: "wx", mode: 0o400 });
    for (const dir of new Set(directories)) await chmod(dir, 0o500);
    return {
      roots,
      executable: executablePath,
      digests,

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the size of the configured ACPX runtime executable (ls -lh / stat) and verify it is the intended bounded binary, not an unstripped or oversized artifact.
2. Reinstall or re-download the correct, official ACPX runtime binary for your platform.
3. Point the driver config at the correct executable path rather than an archive/debug build.
4. If your runtime legitimately needs more space, raise MAX_SNAPSHOT_BYTES in packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts after review.

Example fix

// before
const executable = "./node_modules/.bin/acpx-with-debug-symbols"; // ~400MB
// after
const executable = "./node_modules/.bin/acpx"; // stripped bounded binary under MAX_SNAPSHOT_BYTES

import { statSync } from "node:fs";
const size = statSync(executablePath).size;
if (size > MAX_SNAPSHOT_BYTES) throw new Error(`ACPX runtime binary too large: ${size} bytes`);

When it happens

Trigger: Calling snapshot()/privateSnapshot() on an ACPX driver whose runtime executable (or the sum of all executables being snapshotted in one run) is larger than MAX_SNAPSHOT_BYTES. Thrown mid-loop at the point the cumulative bytesCopied first exceeds the bound.

Common situations: A runtime upgrade or rebuild replaced the executable with a much larger binary (e.g. debug symbols included); multiple executables are being snapshotted together and their combined size exceeds the bound; a misconfigured ACPOX executable path resolves to a huge blob (e.g. an archive or image) instead of the binary.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• ACPX package directory changed while snapshotting
• ACPX runtime snapshot digest mismatch
• ACPX ${agent} runtime executable must be a real regular file
• ACPX ${agent} runtime executable could not be opened as a no
• ACPX ${agent} runtime executable must be a bounded executabl

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