paperclipai/paperclip · error

paperclip_runner_chat_attachment_read_size_mismatch

paperclip_runner_chat_attachment_read_size_mismatch

Error message

paperclip_runner_chat_attachment_read_size_mismatch

What it means

While streaming the object, a running byte counter enforces both the expected source.byteSize and the global MAX_ATTACHMENT_BYTES cap; if either is exceeded mid-stream the stream is destroyed and this error is thrown. It prevents oversized or maliciously growing payloads from being staged into the workspace.

Solutions

1. Verify the stored object matches its metadata (size/hash) or re-upload the attachment.
2. Ensure uploads respect the MAX_ATTACHMENT_BYTES limit configured in attachment-types.
3. Re-run ingest so byteSize metadata reflects the actual object.
4. Investigate the storage writer if objects and metadata diverge repeatedly.

Example fix

// before
await uploadAttachment(bigFile); // > MAX_ATTACHMENT_BYTES; later read throws
// after
if (bigFile.byteLength <= MAX_ATTACHMENT_BYTES) await uploadAttachment(bigFile);

if (declaredByteSize > MAX_ATTACHMENT_BYTES) throw new Error("attachment exceeds maximum allowed size");

try {
  return await scope.read(input);
} catch (e) {
  if (e.message === "paperclip_runner_chat_attachment_read_size_mismatch") {
    return { status: "attachment_oversized_or_corrupt" }; // do not retry
  }
  throw e;
}

When it happens

Trigger: Stored object is larger than the metadata's byteSize recorded at authorization time; attachment exceeds MAX_ATTACHMENT_BYTES; a corrupt/compromised storage object yields extra bytes.

Common situations: Metadata/object divergence after partial writes; uploading files larger than the configured attachment cap; storage objects tampered with or written by a buggy ingest path.

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

• Chat SDK state exceeds the -byte limit
• paperclip_runner_chat_attachment_source_size_mismatch
• ACPX runtime executable digest mismatch
• ACPX private snapshot digest mismatch
• ACPX provider requires verified package snapshots

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/c7e0cf9f416750ca. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/native-runtime/chat-attachment-read.ts:237

      .getObject(this.options.binding.companyId, source.objectKey)
      .then((value) => {
        if (signal.aborted) {
          value.stream.destroy();
          throw new Error("paperclip_runner_chat_attachment_read_aborted");
        }
        object = value;
        return value;
      });
    const read = (async () => {
      const value = await acquiring;
      const chunks: Buffer[] = [];
      let length = 0;
      try {
        for await (const chunk of value.stream) {
          const bytes = Buffer.from(chunk);
          length += bytes.length;
          if (length > source.byteSize || length > MAX_ATTACHMENT_BYTES)
            throw new Error(
              "paperclip_runner_chat_attachment_read_size_mismatch",
            );
          chunks.push(bytes);
        }
      } finally {
        value.stream.destroy();
      }
      const body = Buffer.concat(chunks);
      if (
        length !== source.byteSize ||
        createHash("sha256").update(body).digest("hex") !==
          source.sha256.toLowerCase()
      )
        throw new Error(
          "paperclip_runner_chat_attachment_read_integrity_mismatch",
        );
      return body;
    })();

View on GitHub (pinned to 3f1d897a7c)