A resumable file upload lets a user pause, lose connectivity, refresh a page, or retry a failed request without starting a large transfer from zero. This guide explains how to design a chunked file upload with stable upload IDs, ordered parts, checksums, retries, final assembly, cleanup, and progress reporting—and how to monitor the implementation as browsers, storage providers, and traffic patterns change.
Overview
A large-file upload should be treated as a small workflow rather than one long HTTP request. The browser divides a file into byte ranges, sends those ranges independently, and records enough state to continue later. The server or storage service then verifies the parts and assembles them into the final object.
A typical resumable upload has these stages:
- Initialize: create an upload session and receive an upload ID.
- Plan: determine the file size, chunk size, total part count, and upload endpoint.
- Transfer: upload each chunk, preferably with bounded concurrency.
- Verify: record the server response, part number, size, and optional checksum.
- Complete: ask the server or storage provider to assemble the parts.
- Recover or cancel: resume missing parts, or explicitly remove abandoned state.
The upload ID is the key to pause and resume behavior. It must identify the same logical upload across requests, and the client should persist it together with the file identity and completed parts. For a browser application, local storage or IndexedDB can preserve metadata between page visits; avoid storing the file itself unless the product specifically requires it and the storage model supports that use.
Before choosing a design, decide whether your application needs a standard protocol, direct-to-object-storage uploads, or a small custom API. The right choice depends on authentication, infrastructure, client platforms, expected file sizes, and how much server-side control you need.
| Approach | Best fit | Important considerations |
|---|---|---|
| tus | Applications that want a resumable HTTP protocol and a reusable client/server ecosystem | Check the capabilities of the selected tus implementation, authentication model, storage adapter, and deployment environment. |
| S3 multipart upload | Systems already using compatible object storage and direct browser-to-storage transfers | Track the provider's part-size rules, completion format, expiration behavior, signing flow, and cleanup requirements. |
| Custom HTTP chunking | Products needing full control over metadata, validation, routing, or assembly | You must define idempotency, ordering, checksums, authorization, expiration, error responses, and garbage collection yourself. |
What to track
Upload identity and file identity
At initialization, create an upload record containing an opaque upload ID, the authenticated owner, the original filename, the declared size, the media type, the selected chunk size, creation time, expiration time, and a status such as initiated, uploading, completing, completed, failed, or aborted.
Do not rely on a filename alone to identify a file. A practical client-side fingerprint can combine file size, last-modified time, and a digest when the product's privacy and performance requirements allow it. The server should still authenticate the user and validate every request; a client fingerprint is a convenience, not an authorization mechanism.
Chunk size, ordering, and concurrency
Choose a chunk size that balances request overhead against recovery cost. Small chunks retry cheaply but create more requests. Large chunks reduce request count but waste more data when a connection fails near the end of a request. Treat the initial value as a tunable setting, not a universal constant.
For each chunk, track a zero- or one-based part number consistently, the byte offset, the length, the attempt count, the upload status, the server's part identifier if one exists, and a checksum or equivalent verification value. Sequential uploads are easiest to reason about. Limited parallelism can improve throughput, but excessive concurrency may increase memory use, throttling, and out-of-order state.
Checksums and idempotency
A checksum helps detect truncated or corrupted data and gives the server a way to reject a part that does not match its declared content. Define whether checksums cover each chunk, the complete file, or both. The browser's Web Crypto APIs may be useful for digest work, although hashing a very large file can itself consume time and resources.
Make chunk requests idempotent. If the client retries part 7, the server should either recognize the existing valid part or safely replace it according to a documented rule. A request key built from the upload ID and part number is often useful, but the server must still verify the content and authorization rather than trusting the key.
State-machine template
Use explicit transitions instead of inferring state from a progress percentage:
INITIATED -> UPLOADING -> COMPLETING -> COMPLETED
| | |
v v v
ABORTED PAUSED FAILED
|
v
UPLOADING
A pause should stop scheduling new chunks and abort active requests where possible. It should not delete successfully stored parts. A resume operation should query the server for confirmed parts, reconcile that response with local state, and send only missing or invalid parts.
Progress and user-visible status
Calculate transfer progress from confirmed bytes, not merely from the number of requests started. A simple model is:
confirmedBytes = sum(size of verified parts)
progress = confirmedBytes / totalFileSize
During an active request, you may display an estimated visual value that includes bytes reported by the request's progress event, but reconcile it with confirmed server state after the response arrives. This prevents progress from moving backward unpredictably after a retry and prevents a client from claiming completion before the server has accepted all data.
Expose meaningful states such as “paused,” “retrying,” “waiting for connection,” “verifying,” and “assembling.” The accessible upload guidance on labels, errors, progress, and keyboard support is useful when turning these states into a robust interface.
Cadence and checkpoints
Review a resumable upload implementation at launch, after meaningful infrastructure changes, and on a monthly or quarterly schedule once it is stable. The review should combine application metrics, storage records, browser testing, and failure simulations.
At implementation and pre-release
- Test files smaller than one chunk, exactly one chunk, several chunks, and a file whose size is not evenly divisible by the chunk size.
- Pause during an active request, close the tab, reload the page, and resume with the same upload ID.
- Drop the network between chunks and during a request. Confirm bounded retries and a clear recovery state.
- Send duplicate parts, missing parts, incorrect sizes, invalid checksums, expired IDs, and requests from the wrong user.
- Verify that completion cannot occur until every expected part has been accepted and ordered correctly.
- Test mobile memory pressure, slow connections, browser refreshes, and multiple uploads in one session.
Use request tools and automated tests to exercise the API independently of the interface. The guide to testing file upload APIs with cURL, Postman, and automated requests can help structure those checks. Review the related file upload troubleshooting workflow when failures appear only behind a proxy, CDN, or application server.
Operational metrics to review
Track initialization failures, part failures by status code, retry counts, completion failures, abandoned uploads, average and high-percentile completion time, bytes retransmitted, and the proportion of uploads resumed after interruption. Segment results by browser family, device type, network conditions where available, file-size range, and storage region. These measurements reveal whether a problem is caused by chunk sizing, authentication, an intermediary timeout, storage throttling, or client behavior.
Also monitor the number and age of incomplete storage uploads. Cleanup must be deliberate: retain enough time for legitimate resumes, then abort or remove expired sessions and their parts. Set the policy in one place and log cleanup outcomes so storage does not accumulate invisible cost or stale user data.
How to interpret changes
A rise in retries does not automatically mean the chunk size is wrong. First compare the change with deployments, provider responses, regional traffic, browser versions, and network conditions. A sudden increase in initialization failures suggests an API, authentication, CORS, or request-size problem. A rise in part failures with successful initialization points more toward transport, signing, timeout, or storage behavior.
Completion failures deserve special attention. They can indicate missing part records, inconsistent numbering, an expired upload session, a checksum mismatch, or a race between concurrent requests and the final assembly call. Log a correlation ID, upload ID, part number, attempt number, response status, and sanitized error category. Never log file contents, access tokens, or sensitive metadata unnecessarily.
If users report that progress reaches 100 percent but the file is unavailable, inspect the distinction between client transfer completion and server assembly completion. The interface should reserve its final success state for a confirmed completion response. For secure handling of names, types, and downloaded objects, review the file upload security checklist and the Content-Disposition guide.
When changing chunk size or concurrency, change one variable at a time where possible. Compare completion time, retransmitted bytes, failure rate, memory use, and server load over a representative period. A faster average is not an improvement if poor-network users experience more restarts or if cleanup volume grows sharply.
When to revisit
Revisit this implementation monthly or quarterly, and immediately when any dependency or operating condition changes. Check provider documentation before relying on assumptions about multipart part sizes, expiration, completion requests, signing, or lifecycle cleanup. Storage services and SDKs can change capabilities and limits, so keep those values configurable rather than scattering them through client code.
Review browser support and behavior after major browser releases, especially for file access, request cancellation, progress events, background activity, and Web Crypto APIs. Retest after upgrading the frontend framework, upload library, HTTP client, reverse proxy, CDN, or storage adapter. Repeat the network-failure test suite after changing retry logic, concurrency, authentication, or chunk size.
Use this implementation checklist during each review:
- Confirm that upload IDs are authenticated, opaque, expiring, and safe to resume.
- Confirm that every part has a stable number, byte range, validation rule, and idempotent retry behavior.
- Confirm that local state is reconciled with server state before resuming.
- Confirm that retries use bounded exponential backoff with jitter and stop on non-retryable errors.
- Confirm that pause cancels active work without discarding accepted parts.
- Confirm that final assembly verifies completeness, ordering, ownership, and any required checksum.
- Confirm that abandoned uploads are discoverable and cleaned up after an intentional retention period.
- Confirm that progress, errors, and recovery actions are understandable and keyboard-accessible.
- Confirm that file type, filename, size, authorization, and content validation follow the application's security policy. The MIME types and extensions reference is a useful companion for input handling.
Finally, record the current protocol choice, chunk-size rationale, provider assumptions, state transitions, and test date in the repository. A resumable upload is not finished when the happy path works; it is finished when interruption, duplication, expiration, and recovery are observable and predictable. Rechecking those conditions on a regular cadence keeps large-file support dependable as the surrounding web and storage stack evolves.