{"record":{"id":"bd3aee4d610d8278","repo":"paperclipai/paperclip","slug":"acpx-snapshot-exceeds-its-byte-bound","errorCode":null,"errorMessage":"ACPX snapshot exceeds its byte bound","messagePattern":"ACPX snapshot exceeds its byte bound","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts","lineNumber":195,"sourceCode":"        // Include generated directories in cleanup and read-only sealing.\n        directories.push(join(root, \"node_modules\"), dirname(target));\n        await symlink(pkg.root, target).catch(\n          (error: NodeJS.ErrnoException) => {\n            if (error.code !== \"EEXIST\") throw error;\n          },\n        );\n      }\n    let executablePath: string | null = null;\n    if (executable) {\n      const before = await executable.stat({ bigint: true });\n      if (!before.isFile() || before.size < 1n || before.size > BigInt(MAX_ACPX_RUNTIME_EXECUTABLE_BYTES)) {\n        throw new Error(\"ACPX runtime executable must be a bounded executable file\");\n      }\n      // The bigint bound above makes this conversion exact before allocation.\n      const executableBytes = Number(before.size);\n      bytesCopied += executableBytes;\n      if (bytesCopied > MAX_SNAPSHOT_BYTES) {\n        throw new Error(\"ACPX snapshot exceeds its byte bound\");\n      }\n      const bytes = await readSnapshotBytes(executable, executableBytes);\n      if (!same(before, await executable.stat({ bigint: true })))\n        throw new Error(\"ACPX executable changed during snapshot\");\n      executablePath = join(directory, \"runtime\");\n      await writeFile(executablePath, bytes, { flag: \"wx\", mode: 0o500 });\n      digests[executablePath] = digest(bytes);\n    }\n    const manifest = Buffer.from(\n      JSON.stringify({ roots, executable: executablePath, digests }),\n    );\n    const manifestPath = join(directory, \"manifest.json\");\n    await writeFile(manifestPath, manifest, { flag: \"wx\", mode: 0o400 });\n    for (const dir of new Set(directories)) await chmod(dir, 0o500);\n    return {\n      roots,\n      executable: executablePath,\n      digests,","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts#L177-L213","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Reinstall or re-download the correct, official ACPX runtime binary for your platform.","Point the driver config at the correct executable path rather than an archive/debug build.","If your runtime legitimately needs more space, raise MAX_SNAPSHOT_BYTES in packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts after review."],"exampleFix":"// before\nconst executable = \"./node_modules/.bin/acpx-with-debug-symbols\"; // ~400MB\n// after\nconst executable = \"./node_modules/.bin/acpx\"; // stripped bounded binary under MAX_SNAPSHOT_BYTES","handlingStrategy":"validation","validationCode":"import { statSync } from \"node:fs\";\nconst size = statSync(executablePath).size;\nif (size > MAX_SNAPSHOT_BYTES) throw new Error(`ACPX runtime binary too large: ${size} bytes`);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin the ACPX runtime to a known, stripped binary version.","Verify executable size in your config/startup script before opening the driver.","Never point the driver at archives, debug builds, or container images."],"tags":["filesystem","snapshot","size-limit","acpx"],"backgroundTag":"file-size-limit-exceeded","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}