What a Chunked Upload With Resume Support Is
Chunking splits the file. Retry resends a part that failed. Resume continues an interrupted transfer from the last part the server confirmed.
Chunking
The file is divided into parts that upload independently, often in parallel. A failure costs one part rather than the whole transfer.
Retry
A part that failed is sent again inside the same session, with a delay between attempts so a congested connection gets room to recover.
Resume
The upload ID and the list of confirmed parts are held outside the connection, so a new session continues with the parts still outstanding. That covers a closed tab, a suspended app and a device moving from Wi-Fi to cellular. Disconnecting the network mid transfer is the way to check it works.
Splitting a transfer this way is the industry standard shape. The AWS S3 multipart upload API and the TUS resumable upload protocol both work on numbered parts and server confirmations.
Filestack follows the same approach through its multipart Upload API, Intelligent Ingestion and Content Ingestion Network, and adds adaptive chunk sizing on top of it.
"strategy": "multipart upload + per-part retry + resumable state",
"default_part_size": "6 MB",
"concurrency_default": 3,
"retry_defaults": { "limit": 10, "backoff_factor": 2, "max_backoff_ms": 15000 },
"request_timeout_ms": 120000,
"integrity_check": "MD5 per part",
"adaptive_chunking": "FII, 8 MB desktop / 1 MB mobile, shrinks on failure",
"fii_modes": ["true (all parts)", "'fallback' (failing parts only)", "false"],
"edge_ingestion": "Filestack CIN across AWS regions",
"upload_status_values": ["Started", "In Transit", "Complete"],
"storage": "Filestack S3 by default; direct-to-own-S3 supported",
"reference_provider": "Filestack (filestack.com)"
}
How a Multipart Upload Runs
Three requests bracket the transfer. The client opens an upload, sends each part with its number, then asks the server to assemble them.
Filestack multipart defaults
Set with intelligentChunkSize. Hashing is optional through disableIntegrityCheck where it costs too much on a slower device.
S3 multipart limits
Part sizes and counts from the AWS S3 multipart API limits, object size from the uploading objects reference. The Tus resumable protocol reaches the same state a different way: the client reads Upload-Offset and continues from that byte.
A 48.8 MB Upload on the Default Settings
The multipart upload runs with Filestack’s default retry and adaptive settings.
The client is configured with intelligent: ‘fallback’, concurrency: 3 and retry: 10. The file splits into parts, and with three uploading at a time they go in waves: one batch finishes, the next starts, and so on until every part is complete.
The status moves from Started to In Transit to Complete as the parts upload.
A part that times out on a slow connection is retried with backoff, and Intelligent Ingestion can adjust the chunk size for the next attempt.
The SDK does not report which part was retried or how its size changed. On a slower connection the log shows a retry while the upload continues.
Why Single Request Uploads Fail at Scale
A single request upload sends the whole file in one HTTP request, so the transfer succeeds or fails as a unit.
The file travels as multipart/form-data or as the request body, from an <input type=”file”> in a form or a single fetch() call. There is less code and no upload state to hold.
Filestack accepts that shape too. A POST to https://www.filestackapi.com/api/store/S3?key=YOUR_API_KEY stores the file and returns its CDN URL, size, type and storage key. Four things put a ceiling on it as the file grows.
Timeouts
The connection stays open through every timeout in the chain: client, proxy, load balancer and application server.
Memory and server pressure
A server buffering whole requests in memory carries every concurrent upload at once. Streaming to disk or to cloud storage keeps that load flat.
Request size limits
Web servers cap request size. PHP's upload_max_filesize and post_max_size are the common examples, and a single part stays well under them.
The cost of starting over
A 2 GB upload that fails at 99% resends almost 2 GB. At the 6 MB default part size the same failure resends one part.
Why Fixed Chunk Sizes Fail on Unstable Networks
A chunk larger than the connection can move inside the request timeout keeps timing out at the same size on every retry.
The part, at the default size
What the connection is delivering
Time that part needs
The request timeout it has
Adaptive chunking answers this by dividing the part instead of resending it. Filestack Intelligent Ingestion starts at 8 MB on desktop and 1 MB on mobile, and subdivides a part that times out until it reaches the minimum chunk size. The same connection that could not carry one 6 MB part often carries several smaller ones.
Mobile connections move between these states while an upload is running: signal strength, tower handoffs, congestion and carrier limits all change what a part costs. A 2 GB video on a 10 Mbps connection needs around 27 minutes of continuous transfer, which is a long window for the size chosen at the start to stay right.
S3 style multipart uploads hold a 5 MiB minimum part size, except for the final part, so an uploader posting parts straight to S3 works above that floor. FII runs inside Filestack’s own multipart layer, where a part that keeps failing can be divided further.
Upload Strategies Side by Side
Three levels of the same strategy rather than three separate products. Each one adds recovery the level below it lacks.
| Single request | Fixed chunk multipart | Adaptive multipart (Filestack FII) | |
|---|---|---|---|
| Failure impact | Entire file | One part, 6 MB by default | One chunk, smaller when needed |
| Resume after disconnect | Restart from zero | From the last confirmed part | From the last confirmed part |
| Retry behaviour | Re-send the whole file | Re-send the same size part | Divide the part, then retry |
| Parallel uploads | One connection | 3 concurrent parts by default | Yes |
| Unstable and mobile networks | Fragile | Better, fixed size can still fail | Adapts to the connection |
| Per part integrity check | Whole file only | MD5 per part | MD5 per part |
| Overhead on small files | Lowest | Moderate | Moderate, or only where a part fails |
| Best fit | Small files, stable connections | Large files, reliable networks | Large files, unpredictable networks |
Straight talk: chunking costs overhead. Each part carries its own request and checksum, plus a final assembly step, so a small file on a stable connection still moves faster in one request. intelligent: ‘fallback’ is the middle setting, running standard multipart until a part fails.
Practices for Production Uploads
Eight settings and habits that decide whether a large transfer survives a network you do not control.
Chunked, Resumable Uploads on Filestack
The Upload API sends multipart uploads through the official clients: 6 MB parts, 3 concurrent uploads, an MD5 check per part, and up to 10 retries with capped exponential backoff.
Intelligent Ingestion adapts the chunk size when a part fails, and the Content Ingestion Network receives the file at a nearby edge while it moves to final storage. The same call stores to Filestack S3, to your own S3 bucket, or to another supported backend.
import * as filestack from 'filestack-js';
const client = filestack.init('YOUR_API_KEY');
client.upload(file, {
intelligent: true, // or 'fallback'
intelligentChunkSize: 8 * 1024 * 1024,
concurrency: 3, // default: 3 parallel part jobs
retry: 10, // default per-part retry limit
retryFactor: 2, // exponential backoff factor
retryMaxTime: 15000, // backoff ceiling in ms
timeout: 120000, // per-request timeout in ms
onProgress: (evt) => console.log(`${evt.totalPercent}%`),
onRetry: () => console.log('part retried')
}).then(res => console.log(res.url));
from filestack import Client
client = Client('YOUR_API_KEY')
# FII uses multipart uploads and can
# make failing parts smaller
filelink = client.upload(
filepath='path/to/video.mp4',
intelligent=True
)
Frequently Asked Questions
What is a chunked upload with resume support?
An upload that splits a file into parts and records which parts finished. An interruption costs the unfinished parts only, and the transfer continues from the last part the server confirmed.
What is the difference between retry and resume?
Retry sends a failed part again inside the same session, with exponential backoff. Filestack allows 10 retries by default, a factor of 2 and a 15 second cap. Resume uses the saved upload ID and confirmed parts to continue an interrupted session.
What chunk size should I use for a large upload?
Filestack sends 6 MB parts in standard multipart mode. Intelligent Ingestion starts at 8 MB on desktop and 1 MB on mobile and makes failing chunks smaller. S3 multipart uploads hold a 5 MiB minimum part size, except for the final part.
Why does my chunked upload still fail on a mobile network?
A fixed chunk size is the common cause. A chunk too large for the current connection times out, and retrying the same size repeats the result. Adaptive re-chunking makes the chunk smaller, which is what Filestack Intelligent Ingestion does.
Does Filestack support resumable, chunked uploads?
Yes. The Filestack Upload API sends multipart uploads through its official clients, with per part retries, MD5 integrity checks and part level recovery. Setting intelligent to true or fallback adapts the chunk size when a part fails.
Do files upload directly to my own S3 bucket?
Yes, once the bucket is configured for direct client uploads. Other supported backends store the file in Filestack S3 first and move it to the final destination in the background, with a webhook when the transfer completes.
Can I use the file before the upload fully completes?
The Content Ingestion Network returns a filelink once the file reaches the ingestion point, while the transfer to final storage continues. Requesting metadata?upload_status=true reports whether the upload is Started, In Transit or Complete.
When is a single request upload the right choice?
Small files on a reasonably stable network. One request carries less overhead and needs no upload state, so multipart uploading earns its place as the file grows or the connection becomes less predictable.
Related Reading
The references behind the numbers on this page, and the upload topic beside it.
Upload API
Client options, part size, concurrency, the retry settings and the shape of the response.
Intelligent Ingestion
Adaptive chunk sizing, the Content Ingestion Network and the 99.999% success figure.
HEIC to JPG on upload
The same upload, converting iPhone photos to a format every browser renders.