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

Storage upload 400: diagnose policy, bucket, file

A 400 from storage is the service refusing the request, not a transport problem. Check the three layers in order.

Symptom to cause to confirmation to fix

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.

Verification

Upload a small allowed file to a fresh path as the intended role and confirm success. 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