Tutorials Developer

Handling Large File Uploads in Web Applications

Professional · ~20 min

Overview

A raw video file can easily be several gigabytes, large enough that a single HTTP upload request becomes unreliable on real-world connections, and a dropped connection at 95% means starting completely over. This guide covers the chunked and resumable upload patterns that make large media file uploads actually reliable, independent of any specific storage backend.

What You Need

A server endpoint capable of receiving and storing individual chunks
Client-side JavaScript capable of slicing a File object (the standard File/Blob APIs handle this)

Steps

Recognize why a single request fails at video file sizes

A multi-gigabyte upload in one request is exposed to any single network hiccup for the entire duration. A dropped WiFi connection, a mobile network handoff, or a server-side timeout anywhere in that window loses the entire upload, not just a portion of it.

Split the upload into chunks client-side

Slice the file into fixed-size chunks (a few megabytes each is typical) using the browser's Blob.slice API, and upload each chunk as a separate request. A failure only costs you the current chunk, not the whole file.

Track uploaded chunks so a resume actually works

Persist which chunks have been successfully received, keyed to a specific upload session ID. If the browser tab closes or the connection drops entirely, a resumed upload can query this state and continue from the last successful chunk instead of restarting.

Verify each chunk's integrity before acknowledging it

Compute and compare a checksum for each chunk server-side before marking it received. This catches silent corruption from a flaky connection immediately, rather than discovering it only when the reassembled file fails to process later.

Reassemble and verify the complete file server-side

Once all chunks are received, concatenate them in the correct order and verify the complete file's checksum against what the client reports before considering the upload done, chunk-level verification doesn't guarantee correct reassembly order.

Give users real upload progress and error feedback

Chunked uploads make accurate progress reporting straightforward (chunks completed / total chunks). Use it. Report specific chunk failures rather than a generic "upload failed" so users understand a retry is picking up where it left off, not starting over.

Pro Tips

Choose a chunk size as a deliberate tradeoff, too small adds request overhead per chunk, too large reintroduces the reliability problem you're trying to solve. A few megabytes per chunk is a reasonable starting point to tune from.
Expire incomplete upload sessions after a reasonable window, abandoned partial uploads accumulate storage cost if nothing ever cleans them up.
Test resumability by actually killing a connection mid-upload, not just by reading the code. It's easy to have a subtle bug in resume logic that only shows up under a real interrupted connection.

Knowledge Base

Reliability, Not Just Size, Is the Real Problem

It's tempting to think chunked uploads are purely about getting around a server's request size limit, raising that limit doesn't solve the actual issue. The real problem is that a single long-running request is fragile: any interruption anywhere in a multi-minute upload loses everything. Chunking's real value is bounding the blast radius of a failure to one small chunk instead of the entire file.

Resumability Requires Server-Side State, Not Just Client Retry Logic

A client that simply retries a failed upload from the beginning hasn't actually solved resumability, true resume requires the server to track which chunks it already has, so a resumed upload can skip everything already received. This is the part that's easy to skip and expensive to retrofit later.

Checksums Catch What Retries Alone Miss

A chunk can appear to upload successfully while still being subtly corrupted by a flaky connection, verifying a checksum per chunk (and again on the fully reassembled file) catches this class of silent failure that a naive "did the request return 200" check will miss entirely.

Where This Fits

This guide covers one specific part of building media applications. The wider picture, why media workloads break ordinary web architecture, and the upload, job, and toolchain patterns that handle them, is in Building Media Applications: A Developer Primer, which frames the discipline as a whole and links out to the detailed guides underneath it, including this one. If you are starting from scratch rather than solving a specific problem, read that first and come back here.

FAQ

Q: At what file size do I actually need to worry about chunked uploads?
A: There's no universal cutoff, but once files regularly exceed a few hundred megabytes, a single-request upload becomes noticeably fragile on real-world connections, mobile networks and long-distance connections in particular. If your users are uploading raw video footage rather than small compressed clips, plan for chunking from the start.

Q: Can I just increase my server's request timeout and body size limit instead?
A: That addresses the size limit but not reliability. A single long-running request still fails completely and restarts from zero if the connection drops anywhere in the middle. Chunking solves both problems: each chunk is small enough to complete reliably, and a failure only costs you the current chunk, not the whole upload.