App Finishers

Fix guide · updated 2026-11-16

Supabase Storage "The object exceeded the maximum allowed size"

{"statusCode":"413","error":"Payload too large","message":"The object exceeded the maximum allowed size","code":"EntityTooLarge"}

An upload fails with {"statusCode":"413","error":"Payload too large","message":"The object exceeded the maximum allowed size"}. The file is bigger than a limit Supabase enforces, and two different limits can say no: the bucket's own and the whole project's, fixed at 50 MB on the free plan. We hit both on Supabase Storage itself (version 1.95, November 2026). Here's how to see which one stops you, and how to raise it or send a smaller file.

What the error means

We read the Storage source: before it accepts an upload, it takes the smallest of these limits and refuses anything bigger:

As with every Storage error, the HTTP status is 400 and the real one, 413, is in statusCode. In our test the same message also came back when creating a bucket whose limit was higher than the project's (case 3).

The one-minute check

In the SQL Editor, run:

select id, file_size_limit from storage.buckets;

file_size_limit is in bytes: 10485760 is 10 MB, and empty means the bucket has no limit of its own. Then open Storage → Settings and read Global file size limit. Compare both with the size of the file that failed: in your code it's file.size, in bytes.

1. The bucket's limit is lower than the file

In Storage, edit the bucket: under Restrict file size, raise the File size limit or turn the restriction off. Or in SQL, in bytes:

update storage.buckets set file_size_limit = 20 * 1024 * 1024 where id = 'videos';   -- 20 MB

If an AI tool created the bucket, look at the limit it chose. A small limit is a good habit, as long as it matches the files your app lets people pick.

2. The project's limit: 50 MB on the free plan

On the free plan, the global limit is fixed at 50 MB and the dashboard won't let you raise it. Above that, you can upgrade, or make the files smaller before they leave the browser (see below).

On Pro, raise Global file size limit in Storage → Settings. The dashboard allows up to 50 GB while the spend cap is on, and up to 500 GB once it's off. For anything above 5 GB, switch to resumable uploads (TUS), which Supabase recommends from 6 MB anyway, because a long upload that drops can then resume instead of starting over.

3. Creating a bucket with a bigger limit than the project's

A bucket's limit can't be higher than the global one. In our test, createBucket with a 10,000-byte limit on a project limited to 5,000 bytes failed with "The object exceeded the maximum allowed size", before any file was involved. If setup code or an AI tool creates buckets with a big fileSizeLimit (100 MB on a free project, say), lower it to 50 MB or less.

Stop big files before the upload

Check the size in the browser, so people get a clear message instead of a failed upload:

const MAX_MB = 50;   // the smallest of your limits
if (file.size > MAX_MB * 1024 * 1024) {
  alert(`This file is ${(file.size / 1024 / 1024).toFixed(1)} MB. The limit is ${MAX_MB} MB.`);
  return;
}

For photos, the bigger win is shrinking them before upload: a phone photo of 8 MB is often under 1 MB once resized to 2,000 pixels wide and saved as JPEG or WebP.

"The user_metadata exceeded the maximum allowed size"

Same code, another limit: the metadata you attach to an upload must stay under 1 MB. If the message names user_metadata, the file isn't the problem: something big, a base64 image for example, went into the metadata option. Keep metadata to a few short fields.

If an AI tool built your app

Give your AI tool this prompt, with your own limit:

Before every supabase.storage upload, check file.size. If it's over 50 MB, don't upload: show "This file is too big (maximum 50 MB)". For images, resize them in the browser to at most 2000 pixels wide and compress them as JPEG or WebP before uploading. Don't change anything else.

Raising a limit (cases 1 and 2) is a dashboard setting, so that part stays with you.

Not quite your error?

Still stuck?

If the file is smaller than every limit in the one-minute check and the upload still fails with this message, compare sizes in bytes, not megabytes: Supabase counts 1 MB as 1,048,576 bytes. Then check the request in your browser's Network tab: its address names the bucket, and its size is the real size that was sent.

Other Supabase problems? See Supabase fixes.