Multipart Upload
Last updated: 2026-10-25
S4 supports S3-compatible multipart uploads for large files. The AWS CLI and SDKs use multipart upload automatically for files larger than a configurable threshold (typically 8MB).
How It Works
- Initiate — create a multipart upload and receive an upload ID
- Upload Parts — upload the file in chunks, each identified by a part number
- Complete — finalize the upload by listing all parts
Parts are stored individually in volume files. On completion, they are logically combined without copying data.
In cluster mode, multipart upload state is quorum-replicated: session creation,
each UploadPart, CompleteMultipartUpload, and abort are sent to the bucket's
replica set and acknowledged by the configured write quorum. A load balancer may
round-robin multipart requests across nodes; sticky sessions are not required.
Part data is sent between nodes using streaming gRPC chunks, so ordinary AWS CLI
multipart chunks such as 64MB are not constrained by unary gRPC message limits.
Before completing a multipart upload in cluster mode, S4 inspects the replica set and validates the requested part list against replica-local multipart metadata. Replicas only acknowledge completion if their local durable part records and blob references match the selected parts. This prevents a node that missed a part from publishing a corrupt composite object.
Disk Space in Single Mode
UploadPart and UploadPartCopy return HTTP 507 with XML code InsufficientStorage when their
physical allocation cannot preserve the disk reserve. UploadPart also accepts a body without
Content-Length: it checks room before writing each portion, enforces the upload size limit and
removes an unfinished tail on refusal. A refused replacement preserves the previous part.
AWS chunked uploads count decoded data bytes and still validate framing and trailers.
CompleteMultipartUpload reserves space for the manifest and metadata, not another copy of the
parts. It completes before response headers, so a space refusal is an actual HTTP 507. The upload
remains available for retry or abort with its parts intact. Once local completion starts it continues
even if the HTTP connection closes; a lost response does not establish whether completion succeeded.
AbortMultipartUpload can use the disk reserve for cleanup metadata and returns 507 if it cannot
fit. Removing part references does not immediately free bytes in volume files.
In cluster mode, session, part, completion and abort mutations require the configured write quorum.
A full replica refuses data while continuing to accept cleanup that fits in the reserve. When
space refusals prevent quorum, the coordinator returns 507; a remaining quorum can still complete
the request. A refused local completion obtains no new state and preserves its parts for retry.
Some replicas may already have completed a request that returned a cluster error or lost its response.
Updated nodes keep deferred delivery until space returns; older coordinators may return 503
during a rolling upgrade.
AWS CLI
The AWS CLI handles multipart upload automatically:
# Large files are automatically uploaded using multipart
aws --endpoint-url http://localhost:9000 s3 cp large-file.zip s3://mybucket/large-file.zip
To control the multipart threshold and chunk size:
aws configure set s3.multipart_threshold 64MB
aws configure set s3.multipart_chunksize 16MB
Manual Multipart Upload (s3api)
# 1. Initiate multipart upload
UPLOAD_ID=$(aws --endpoint-url http://localhost:9000 s3api create-multipart-upload \
--bucket mybucket \
--key large-file.zip \
--query 'UploadId' --output text)
# 2. Upload parts
aws --endpoint-url http://localhost:9000 s3api upload-part \
--bucket mybucket \
--key large-file.zip \
--part-number 1 \
--upload-id $UPLOAD_ID \
--body part1.bin
aws --endpoint-url http://localhost:9000 s3api upload-part \
--bucket mybucket \
--key large-file.zip \
--part-number 2 \
--upload-id $UPLOAD_ID \
--body part2.bin
# 3. Complete multipart upload
aws --endpoint-url http://localhost:9000 s3api complete-multipart-upload \
--bucket mybucket \
--key large-file.zip \
--upload-id $UPLOAD_ID \
--multipart-upload '{"Parts":[{"PartNumber":1,"ETag":"etag1"},{"PartNumber":2,"ETag":"etag2"}]}'
Abort Multipart Upload
If you need to cancel an in-progress upload:
aws --endpoint-url http://localhost:9000 s3api abort-multipart-upload \
--bucket mybucket \
--key large-file.zip \
--upload-id $UPLOAD_ID
Upload Size Limit
The maximum upload size per request is controlled by the S4_MAX_UPLOAD_SIZE environment variable (default: 5GB). This applies to both single-part and multipart uploads.