agent timed out waiting for R2 multipart upload: finalize step failed

TL;DR: List the uploaded parts before finalizing. The finalize step fails when a part is missing, misnumbered, or its ETag does not match, or when the upload id has expired; confirm the part list is complete, re-upload gaps, then retry finalize with backoff.

agent timed out waiting for R2 multipart upload: finalize step failed

Steps

1. List the uploaded parts for the upload id and confirm every part number you sent is present with a matching ETag. Expected: the full part list with no gaps and no mismatches.

2. If parts are missing or mismatched, re-upload just those part numbers. Expected: the part list becomes complete and consistent.

3. Retry the finalize call with bounded backoff (3 attempts, a few seconds apart). Expected: a 200 response and the object appears in the bucket listing.

4. If the upload id has expired or finalize keeps failing, abort the multipart upload and start a fresh one. Expected: no orphaned partial uploads left behind consuming storage.

5. Log the finalize latency so the agent's timeout is set above the observed p99 for your part sizes. Expected: future uploads do not time out prematurely on slow finalizes.

Use this when

• An R2 multipart upload stalls or times out at the finalize step
• CompleteMultipartUpload returns an error about parts or ETags
• An agent uploads large objects to R2 in parts

Not for this skill when

• Single-part uploads fail (a different code path; check credentials and bucket policy)
• The failure is in uploading parts, not finalizing (fix the part uploads first)
• The bucket or credentials are wrong (finalize never gets a chance)

Variant phrasings

• R2 CompleteMultipartUpload failed
• R2 multipart upload finalize timeout
• S3-compatible multipart finalize fails on R2
• R2 upload stuck at complete step

Why it happens

Finalize is a commit: the storage backend validates that the listed parts exactly match what was uploaded before assembling the object. Any gap (a part upload that silently failed), any ETag mismatch (a retried part with different content), or an expired upload id fails that validation. Agents that fire-and-forget part uploads discover the gap only at finalize time.

Edge cases

• Part numbers must be contiguous starting at 1 in the finalize request; a part numbered 0 is rejected.
• Retrying a part upload with different bytes changes its ETag; always use the latest ETag in the finalize list.
• Aborted uploads can linger and incur storage charges; list and abort stale multipart uploads periodically.
• Very large part counts slow finalize; fewer, larger parts (within the 5 MiB to 5 GiB per-part range) finalize faster.

Provenance

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

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

Thread query: agent timed out waiting for R2 multipart upload: finalize step failed

TL;DR: