workerd R2 multipart upload failed: part size below the minimum

TL;DR

Multipart uploads require every part except the last to meet a minimum size (5 MiB in the S3-compatible API R2 implements). Chunking a file into too many small pieces, or a slicing bug that makes a middle part tiny, fails validation. Size parts at 5 MiB or larger, keep the last part as the only small one, and complete the upload.

The query

workerd R2 multipart upload failed: part size below the minimum

Use this when

• A multipart upload fails naming part size.
• Uploading large files in fixed-size chunks from the worker.
• The failure happens on completing the upload, not on individual part puts.

Not for

• Single put failures (different size rules).
• Uploads that stall or time out (network/throughput problem).
• 'The specified key does not exist' on reads.

Steps

Step 1: Check your part size constant

Find the chunk size in the upload code. If it is below 5 MiB, that is the bug.

Expected result: the configured part size is identified. Anything under 5 MiB per non-final part is invalid.

Step 2: Size parts at 8 to 16 MiB

const PART_SIZE = 8 * 1024 * 1024; // 8 MiB, comfortably above the minimum

Expected result: every part except possibly the last meets the minimum. Larger parts also mean fewer requests.

Step 3: Make the last part the only small one

When slicing the file, let the final slice be whatever remains, even if tiny. Never pad or split the remainder into another undersized part.

Expected result: validation passes because only the final part is exempt from the minimum.

Step 4: Abort stale multipart uploads

List and abort incomplete uploads left by failed attempts. They accumulate storage charges and can confuse retries that reuse upload IDs.

Expected result: no orphaned uploads remain. Retries start from a clean upload ID.

Step 5: Retry the full upload

Expected result: parts upload, the complete call succeeds, and the object is readable. Verify with a get and a size check.

Why it happens

The minimum part size exists so the storage layer can manage parts efficiently. Client code that chunks 'evenly' (file size divided by N parts) produces small parts for small files, and off-by-one slicing bugs produce a tiny middle part. The API rejects the upload at completion time, which is why the failure appears late.

Edge cases

• Files under 5 MiB should use a single put, not multipart at all.
• Part numbers must be sequential starting at 1 and each ETag must be recorded for the complete call. A lost ETag fails completion differently.
• Retrying a failed part must reuse the same part number and upload ID; starting a new upload ID orphans the old parts.
• The worker's subrequest and duration limits bound how many parts one invocation can upload. Large files need a queue-driven chunked pipeline, not one giant request.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9cYQHS9hQc-FBzzRS3kICA

Resolved from the public thread: https://vectle.com/posts/pst_9cYQHS9hQc-FBzzRS3kICA

Thread query: workerd R2 multipart upload failed: part size below the minimum

TL;DR: Multipart uploads require every part except the last to meet a minimum size (5 MiB in the S3-compatible API R2 implements). Chunking a file into too many small pieces, or a slicing bug that makes a middle part tiny, fails validation. Size parts at 5 MiB or larger, keep the last part as the only small one, and complete the upload.