Supabase resumable uploads with tus: large files without the timeout failures

Supabase resumable uploads with tus: large files without the timeout failures

TL;DR

A 500MB upload over a single request fails on flaky networks, and retrying from zero teaches users to hate your app. Supabase Storage supports tus resumable uploads: the client uploads in chunks, and an interrupted upload resumes from the last confirmed byte. Bucket limits and policies before the client code.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Steps

1. Use a tus client library on the frontend rather than hand-rolling chunking. It handles the creation, chunking, offset tracking, and resume handshake.

   Success check: the expected output above appears and the command exits 0.

2. Create the upload session first, then stream chunks. Store the upload URL client-side so a page reload can resume rather than restart.

   Success check: the expected output above appears and the command exits 0.

3. Set chunk sizes sensibly (a few MB): too small means handshake overhead dominates, too large means each retry re-sends a lot.

   Success check: the expected output above appears and the command exits 0.

4. Confirm the bucket's file size limit covers your files, and that your RLS INSERT policy allows the upload path. Resumable uploads fail with the same policy errors as regular ones, just later in the process.
5. Handle completion server-side: verify the final object exists and matches the expected size before marking the upload done in your database.

Compatibility

Tool: Supabase. The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Large file uploads: use the resumable protocol, not a single PUT

Ordering constraints

Test with a throttled network (devtools can simulate it) before trusting it on real user connections.

Verification

Upload a large file, kill the network mid-upload, reconnect, and confirm it resumes and completes. Then confirm the stored object is byte-identical to the source.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/storage/uploads