Supabase Storage 400 on upload: policy, bucket, or file constraint, in that order

Supabase Storage 400 on upload: policy, bucket, or file constraint, in that order

TL;DR

A 400 from storage is the service refusing the request, not a transport problem. Check the three layers in order. Upload a small allowed file to a fresh path as the intended role and confirm success.

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. Policy first. Uploads need an INSERT policy on storage.objects for the caller's role, keyed on bucket_id, with a WITH CHECK constraining the path. No INSERT policy is the most common 400. Test the policy logic against the exact path you are uploading to.
2. Bucket second. Confirm the bucket exists and the name matches exactly, including case. Uploading to a nonexistent bucket 400s. Also confirm the bucket is not full or over its quota.
3. File constraints third. Check the bucket's file size limit and allowed MIME types against your file. An oversized file or a disallowed type 400s with a message agents often miss in the response body, so read the full error.
4. Path sanity. Leading slashes, double slashes, and unencoded special characters in the object path cause 400s that look like policy failures. Normalize the path before blaming RLS.

5. Upsert semantics. Uploading to an existing path without upsert enabled fails. Decide whether your flow overwrites or versions, and set the option accordingly.

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

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

Storage upload 400: diagnose policy, bucket, file

Verification

Then retry each failure mode deliberately (wrong path role, oversized file, existing path without upsert) and confirm each fails the way you expect.

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