{"record":{"id":"f3a3714c55b1dd7e","repo":"paperclipai/paperclip","slug":"acpx-package-snapshot-exceeds-its-byte-bound","errorCode":null,"errorMessage":"ACPX package snapshot exceeds its byte bound","messagePattern":"ACPX package snapshot exceeds its byte bound","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts","lineNumber":123,"sourceCode":"      if (mapped) await symlink(mapped, target);\n      return;\n    }\n    if (!within(root, await realpath(source)))\n      throw new Error(\"ACPX snapshot escaped its package\");\n    if (before.isDirectory()) {\n      await mkdir(target, { mode: 0o700 });\n      directories.push(target);\n      for (const entry of await readdir(source))\n        await copy(join(source, entry), join(target, entry), root);\n      if (!same(before, await lstat(source, { bigint: true })))\n        throw new Error(\"ACPX package directory changed during snapshot\");\n      return;\n    }\n    if (!before.isFile() || before.size > 16n * 1024n * 1024n)\n      throw new Error(\"ACPX module must be a bounded regular file\");\n    bytesCopied += Number(before.size);\n    if (bytesCopied > MAX_PACKAGE_SNAPSHOT_BYTES)\n      throw new Error(\"ACPX package snapshot exceeds its byte bound\");\n    const handle = await open(\n      source,\n      constants.O_RDONLY | constants.O_NOFOLLOW,\n    );\n    try {\n      if (!same(before, await handle.stat({ bigint: true })))\n        throw new Error(\"ACPX module changed before snapshot\");\n      const bytes = await readSnapshotBytes(handle, Number(before.size));\n      if (\n        !same(before, await handle.stat({ bigint: true })) ||\n        !same(before, await lstat(source, { bigint: true }))\n      ) {\n        throw new Error(\"ACPX module changed during snapshot\");\n      }\n      await writeFile(target, bytes, { flag: \"wx\", mode: 0o400 });\n      digests[target] = digest(bytes);\n    } finally {\n      await handle.close();","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/private-snapshot.ts#L105-L141","documentation":"copy() accumulates the byte size of every regular file it copies and enforces MAX_PACKAGE_SNAPSHOT_BYTES across the whole snapshot. When the cumulative total exceeds that bound it throws, refusing to build a snapshot larger than the configured memory/disk budget. Each individual file is separately capped at 16 MiB, so this fires on aggregate volume.","triggerScenarios":"createAcpxPrivateSnapshot over a package root whose total regular-file bytes exceed MAX_PACKAGE_SNAPSHOT_BYTES; the failure can occur partway through the walk, after many files have already been copied.","commonSituations":"Admitting a data-heavy package (fixtures, media, generated bundles); accidentally snapshotting node_modules or a monorepo root as a single package; a dependency that ballooned after a version upgrade.","solutions":["Reduce the package root to the minimal package directory actually needed for import","Purge generated/binary assets from the root before snapshotting","Check whether a dependency upgrade grew the tree; pin the smaller version","Coordinate with the runner maintainers to raise MAX_PACKAGE_SNAPSHOT_BYTES if the workload legitimately needs it"],"exampleFix":"// before\nroots: [repoRoot]\n// after: admit only the needed package\nroots: [join(repoRoot, 'packages/util')]","handlingStrategy":"validation","validationCode":"let total = 0;\nfor (const f of await walkFiles(root)) {\n  total += (await fs.stat(f)).size;\n}\nif (total > MAX_PACKAGE_SNAPSHOT_BYTES) throw new Error(`package bytes ${total} exceed snapshot budget`);","typeGuard":null,"tryCatchPattern":"try {\n  await createAcpxPrivateSnapshot({ roots: [root] });\n} catch (e) {\n  if (e.message.includes('exceeds its byte bound')) {\n    throw new Error(`Reduce package ${root} below the snapshot byte budget or split roots`);\n  }\n  throw e;\n}","preventionTips":["Admit minimal package roots, not whole trees","Purge binary/generated artifacts before packaging","Track dependency payload growth across upgrades"],"tags":["filesystem","limit","snapshot","resource-exhaustion"],"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-14T00:17:10.932Z"}