Large Files

Files under the multipart threshold go up as a single presigned PUT. Files over it are cut into parts, which is what makes pause, resume and per-part retry possible. This page covers where the threshold sits, what changes on each side, and how the browser runs a multipart upload.

import { uploadHandler, uniquePath } from "@upstash/blob"export const uploads = uploadHandler({  multipart: "100mb", // everything up to 100 MB goes up as one PUT  onBeforeUpload: ({ file }) => ({ path: uniquePath`uploads/${file.name}` }),})

The multipart threshold#

The default is 16 MB decimal, 16,000,000 bytes. A 16,000,000 byte body is a single PUT; 16,000,001 is multipart. Sizes are decimal everywhere. bucket.put() on your server and a direct browser upload use the same threshold.

The row that matters most is when the object comes into existence. Under the threshold the object is stored the moment the last byte lands, before your route has been told anything. Over the threshold nothing exists at the path until the upload is completed. See Abandoned uploads for what that means when a tab closes.

Parts are not free. A single PUT is one round trip; a multipart upload is three plus one per part.

Changing the threshold#

export const uploads = uploadHandler({  multipart: "100mb",  routes: {    avatar: {      multipart: false, // never parts      onBeforeUpload: ({ file }) => ({ path: uniquePath`avatars/${file.name}` }),    },    video: {      multipart: true, // always parts      onBeforeUpload: ({ file }) => ({ path: uniquePath`videos/${file.name}` }),    },  },})

await bucket.put("videos/clip.mp4", file, { multipart: true })await bucket.put("logs/today.ndjson", stream, { size, multipart: "50mb" })

multipart takes a size, true or false. A size becomes the threshold for that handler, route or write; true always uses parts; false never does. On a handler it is the default for every route, and a route overrides it.

• multipart: false on a body over the single-PUT ceiling of about 5 GiB throws too_large.
• On bucket.put(), allowOverwrite: false and ifUnchanged are single-PUT only; see Conditional writes.
• An unparseable size ('100 megs') throws at startup, where the option is written.

multipart: true costs no extra browser requests, only two extra round trips between your server and storage.

Part sizing#

The part size is derived from the file size, never configured. The SDK aims at roughly 250 parts, with a floor of 5 MiB. A failed part costs at most one part's worth of re-sent bytes.

Four parts upload at once per file, and the whole page shares a cap of six requests in flight. Part URLs are presigned in batches as the upload needs them.

Progress and status#

{upload.pending && <progress value={upload.percent} max={100} />}{upload.status === "finishing" && <p>Finishing up...</p>}{upload.stalled && <p>Connection is struggling, retrying...</p>}

Every record carries the same fields on either side of the threshold:

percent is capped at 99 because 100 means stored, not sent. It stays there through status finishing, while your onUploadComplete runs. Render that state so the bar does not look stuck.

A failed part's bytes are subtracted from loaded again, because they were never stored.

Pause and resume#

{upload.canPause && upload.status === "uploading" && (  <button onClick={() => upload.pause()}>Pause</button>)}{upload.status === "paused" && (  <button onClick={() => upload.resume()}>Resume</button>)}

A single PUT cannot pause, since stopping it would throw its bytes away. While queued the SDK does not yet know which kind the upload is. From finishing there is nothing left to hold back.

Pause stops the queue, not the parts in flight. A part that has already sent bytes finishes and keeps them. Only parts that have sent nothing go back to the queue. resume() picks up from there and nothing that landed is sent again.

Resuming after a reload#

A closed tab is not a canceled upload. When an upload starts, the client remembers it in localStorage, keyed by the route, the file name, the size and its last-modified time.

The user picking the same file again resumes it. There is no API to call. On a match the SDK asks your server which parts landed and sends only the missing ones. onBeforeUpload does not run again, so a row it inserted is not written twice.

• The browser is not trusted about what landed. Your server reads it back from storage.
• A mismatch is a fresh upload, never an error. A different file, a different size, or an expired upload starts over.
• A single PUT has nothing to resume. The file is simply sent again.

Resume is best effort. Private mode or a browser with no localStorage means no resume, never a failed upload.

Retries#

{upload.status === "error" && (  <button onClick={() => upload.retry()}>{upload.error.message}</button>)}

Parts are retried on a network failure and on 408, 429, 500, 502, 503 and 504, with an exponential backoff that honors Retry-After. A 403 is treated as an expired signature first: the SDK asks your route for fresh URLs and sends the part again. Only a freshly signed URL refused a second time is reported as signature_mismatch.

When the retry budget runs out the record settles as error with a BlobError. retry() runs the same upload again from the parts that landed, and replaces done with a fresh promise.

Cancel#

cancel() aborts the parts in flight and tells your route to abort the multipart upload, so the parts stop costing storage. For a single PUT, it deletes the object if the bytes already landed and they belong to this upload.

From status finishing only the local task is canceled. Your onUploadComplete may already have written a row, so deleting the object at that point could remove a file your app thinks it has.

Large writes from the server#

import { Bucket } from "@upstash/blob"const bucket = Bucket.fromEnv()export async function archive(stream: ReadableStream<Uint8Array>, size: number) {  // Pass size for a stream whose length is not otherwise known, or put() buffers  // it to find the content length.  return await bucket.put("backups/2026-01.tar", stream, { size })}

bucket.put() uses the same threshold and the same multipart option. Over the threshold it streams the body one part at a time, and any failure aborts the upload rather than leaving billed parts behind. An unknown-length stream with neither size nor maxSize throws length_required; see Streams and unknown lengths.

Next steps#