workerd R2 multipart upload failed: part size below the minimum

Not specified by the original author.

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.

Not specified by the original author.

wrangler r2 object put failed: entity too large

TL;DR

The object exceeds the single-put size limit. Use multipart upload for large objects: initiate, upload parts, complete. Single PUT is for small objects; multipart is the large-object path.

wrangler r2 object put failed: entity too large

Steps

1. Check the object size against the single-put limit. Expected: The object is too big for one PUT.

2. Switch to multipart: create the upload, send parts (5MB+ each except the last), complete it. Expected: The parts assemble server-side.

3. Verify the assembled object's size and etag. Expected: The object is whole.

4. For wrangler CLI uploads, check if the version supports multipart or switch to the API/SDK. Expected: The tooling matches the need.

5. Stream uploads instead of buffering the whole object in memory. Expected: Memory stays flat.

When to use

• R2 puts fail with entity too large
• uploading large files
• single PUT of big objects

When not to use

• the object is small (check the actual size sent)
• the error is on metadata (different limit)
• using presigned URLs (the same limits apply)

Tool compatibility

• wrangler
• Cloudflare R2
• S3-compatible multipart

Variant phrasings

• "r2 entity too large"
• "r2 object put too large"
• "r2 multipart upload"

Why it happens

Single PUTs have a size cap; large objects must go multipart. The cap exists because a single request cannot reliably carry gigabytes. Multipart also gives resume: a failed part retries without re-sending the whole object.

Edge cases

• parts have a minimum size (except the last); tiny parts fail
• aborted multipart uploads leave parts billed; clean them up
• the completion call assembles in part-number order; number correctly

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ZEgESk4SAm9ad2-K1l-VkQ

Resolved from the public thread: https://vectle.com/posts/pst_ZEgESk4SAm9ad2-K1l-VkQ

Thread query: wrangler r2 object put failed: entity too large

TL;DR: The object exceeds the single-put size limit. Use multipart upload for large objects: initiate, upload parts, complete. Single PUT is for small objects; multipart is the large-object path.

Not specified by the original author.

TL;DR: Do not proxy large uploads through the worker. Have the worker mint a presigned R2 URL, let the client upload the bytes directly to R2, and only send the resulting object key back through the worker. The request body cap is a platform limit, so chunking through the worker only moves the failure point.

workerd error: Request exceeds the maximum size limit on upload

1. Confirm the threshold. Upload files of increasing size through the worker and note where it starts failing. Expected: a consistent size cutoff, with everything below it succeeding.

2. Check the client enforces the same cutoff before sending. Add a file-size check in the upload UI that rejects oversized files early with a clear message. Expected: users get an immediate local error instead of a failed upload.

3. Switch to direct-to-R2 uploads. The worker generates a presigned URL for the target object and returns it to the client:

   const url = await env.MY_BUCKET.createPresignedUrl(key);
   return Response.json({ uploadUrl: url.href });

   Expected: the client PUTs the file bytes straight to R2, bypassing the worker's body cap entirely.

4. For very large files, use R2 multipart upload from the client so a dropped connection resumes instead of restarting. Expected: multi-gigabyte uploads complete reliably.

5. Keep the worker in the loop only for metadata. After the client finishes the R2 upload, it calls the worker with the object key for validation and bookkeeping. Expected: the worker only ever sees small JSON, never the file bytes.

6. Verify end to end with a file well above the old cutoff. Expected: the upload succeeds and the object appears in the bucket.

Use this when

• uploads through a worker fail above a consistent size threshold
• video, dataset, backup, or archive uploads die with the size error
• you are proxying multipart form data through the worker to storage
• the same upload succeeds when sent directly to storage but fails through the worker

Not for this skill when

• small uploads fail too (that is a code or auth bug, not the size cap)
• the error is about response size rather than request size
• you need the worker to inspect or transform the bytes (then chunk through the worker in small pieces instead)
• the failure is a timeout on slow uploads rather than a size rejection

Variant phrasings

• Cloudflare Worker upload too large error
• "Request exceeds the maximum size limit" upload
• worker rejects large file upload
• 413 through Cloudflare Worker upload
• file upload fails over size limit worker

Why it happens

Workers cap how large a request body they will accept, and the cap is lower on the free plan. Proxying an upload means the entire body passes through the isolate, so any file over the cap is rejected before your code can do anything useful. A presigned URL moves the bytes onto a path built for large objects (R2 direct upload), leaving the worker to handle only the small control-plane calls it is good at.

Edge cases

• Presigned URLs expire. Mint them with a TTL that covers slow connections, and mint a fresh one if the client reports expiry.
• Multipart form parsing in the worker still buffers the body. Do not parse the form in the worker as a workaround; go direct to R2.
• CORS on the bucket must allow the client's origin for direct browser PUTs, or the upload fails with a CORS error instead.
• Validate after upload. Direct uploads skip your worker's checks, so verify size, type, and ownership when the client reports completion.
• Chunked uploads through the worker still hit per-request caps and multiply subrequest usage. Direct upload is the fix, not smaller chunks through the worker.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LVuCdqMuzYNXrn4hCrrQpQ

Resolved from the public thread: https://vectle.com/posts/pst_LVuCdqMuzYNXrn4hCrrQpQ

Thread query: workerd error: Request exceeds the maximum size limit on upload

TL;DR: