A visitor picks a profile photo, a receipt or a document, presses upload, and nothing happens. Or the upload works but the picture never appears. If your site stores files in Supabase Storage (most Lovable, Bolt, v0 and Cursor builds that handle files do), the problem is almost always one of six things:
- "Bucket not found" when uploading, or when an image loads
- "new row violates row-level security policy" or a 403 on upload
- "Payload too large" / "The object exceeded the maximum allowed size" (413)
- a 400 about the file's type (MIME type) not being allowed
- "The resource already exists" (409) when someone uploads a second time
- the upload succeeds, but the image is broken on the page
Each one has a different cause, so start by finding out which one you have.
Step 1: find the real error
Open your live site in a private window, open DevTools (F12) and go to the Network tab. Try the upload as a normal test user, not as yourself.
- Look for a request to
/storage/v1/object/<bucket>/<path>. Click it and read the status and the response body. - For a broken image, find the image request instead. Its URL tells you a lot:
/storage/v1/object/public/...means your site built a public link. - If there's no storage request at all, the upload never left the page. Check the Console tab for a JavaScript error, and see "Uploads that go through a server function" below.
Keep in mind that Storage sometimes sends one status on the request and another inside the body. "Bucket not found" can arrive as an HTTP 400 with "statusCode": "404" in the JSON. Code that only checks for a 404 will miss it.
2. "Bucket not found" on upload
An upload only works into a bucket that already exists. Supabase does not create buckets on the fly. On an upload, "Bucket not found" means that bucket name doesn't exist in the project your site is talking to. It is not a permissions problem; a permissions problem gives a row-level security error instead (section 4).
Check, in this order:
- The exact name. Open Storage → Buckets in the Supabase dashboard and compare it with the name in your code, letter for letter, including capitals and dashes.
Avatars,avatarandavatarsare three different buckets. - The project. Your site talks to exactly one Supabase project: the one in its Supabase URL (an environment variable such as
VITE_SUPABASE_URLorNEXT_PUBLIC_SUPABASE_URL). If you have a test project and a live one, or your builder connected a fresh project when you remixed or re-deployed, the bucket may live in the other one. Compare the project reference in that URL with the one in your dashboard address bar. - The bucket was ever created. AI builders often write upload code for a bucket they never create, or create it in a migration that didn't run on the live project. If it isn't in the list, create it and choose public or private on purpose.
3. "Bucket not found" when an image loads
This is the one behind most broken pictures. The upload worked, the file is in the bucket, but the page shows a broken image and opening its address gives "Bucket not found".
The cause: the link was made with getPublicUrl, and the bucket is private. getPublicUrl doesn't ask Supabase anything; it just joins your project address, the bucket and the file name into a /storage/v1/object/public/... link. Supabase's own reference says it does not check whether the bucket is public. When a visitor opens that link, Storage only looks among public buckets, so a private bucket answers exactly like a missing one.
Fix, by what the files are:
- Files anyone may see (product photos, blog images, logos): make the bucket public in Storage → Buckets → Edit bucket. Anyone with the link can then open those files, permanently.
- Files that belong to one person (ID documents, invoices, private photos): keep the bucket private and replace
getPublicUrlwith a signed link:supabase.storage.from("documents").createSignedUrl(path, 3600)gives a link that works for an hour. Signed links still respect your policies, so the person asking needs a SELECT policy that lets them read that file (section 4).
Tell your builder plainly: "for this bucket, keep it private, replace getPublicUrl with createSignedUrl, and add a storage policy so each user can only read their own files."
If files upload fine in preview but show blank or 403 only on the live site, see Uploads work, files 403? Fix Storage.
4. "new row violates row-level security policy" or 403 on upload
Supabase Storage keeps a row for every file in the storage.objects table, and row-level security applies to it. With no policy, uploads are blocked, even into a public bucket. ("Public" only controls who can read files by link.)
What each action needs on storage.objects:
- Upload a new file: an INSERT policy.
- Overwrite with
upsert: true: INSERT, SELECT and UPDATE. - Delete: DELETE (and usually SELECT).
- Signed links and downloads from a private bucket: SELECT.
A safe pattern is one folder per user, with the policy limited to your bucket:
create policy "Users upload to their own folder"
on storage.objects for insert to authenticated
with check (
bucket_id = 'avatars'
and (storage.foldername(name))[1] = auth.uid()::text
);
Your code then uploads to `${user.id}/avatar.png`. Add matching SELECT and UPDATE policies if you overwrite files.
Two more causes of a 403 here:
- The user isn't signed in when the upload runs. The request goes out with the public key only, so
auth.uid()is empty and the policy says no. Check that the request carries the user's session (theAuthorizationheader holds a long token, not just your anon key). - An expired session gives a 401 with an invalid-token error instead. Signing out and back in confirms it.
Policies on your own tables follow the same rules; here the table is storage.objects.
5. 413 "Payload too large"
The file is bigger than the limit that applies to it. There are two limits:
- Global file size limit (Storage settings). On the Free plan it can't be set above 50 MB; paid plans can go much higher.
- Per-bucket limit ("Restrict file size" when you edit a bucket). It can't be higher than the global one.
Fix: check both, and raise the one that's too low, within your plan. Then add a size check in the page before uploading, with a friendly message ("Files up to 10 MB"), so visitors aren't left staring at a spinner.
For large files, Supabase recommends resumable uploads above about 6 MB.
6. 400: file type not allowed
If a bucket has Allowed MIME types set (for example image/png, image/jpeg), any other type is rejected with a 400. Two common surprises:
- iPhone photos can arrive as
image/heic, which a JPEG/PNG-only bucket refuses. - No content type sent. Pass it explicitly:
upload(path, file, { contentType: file.type }).
Fix: either add the types you really accept to the bucket, or convert the file before uploading. Make the file picker match (accept="image/png,image/jpeg").
7. 409 "The resource already exists"
By default, uploading to a path that already has a file fails rather than overwrite it. The first upload works; the second one (say, a new profile photo with the same file name) fails.
Fix, pick one:
- Give every upload a unique path, for example
`${user.id}/${crypto.randomUUID()}.jpg`, and save the path in your table. This also avoids old images being served from cache. - Or overwrite on purpose with
{ upsert: true }, and add the SELECT and UPDATE policies from section 4. Without them, upsert fails with an RLS error and looks like a different bug.
Uploads that go through a server function
Some builders route uploads through a server function or Edge Function instead of uploading from the browser. Common breakages:
- The file never arrives. Passing a browser
Fileobject into a server action or function doesn't always serialise it. Uploading straight from the browser with the signed-in user's session is simpler and lets your policies do the checking. If you need a server step, have the server create a signed upload URL (createSignedUploadUrl) and upload to it from the browser withuploadToSignedUrl. - The server uses the wrong key or project. A function that works in preview but not live is usually missing its production secrets. See Lovable site works in preview but not when published.
- The service role key leaks. It bypasses every policy, so it must never reach the browser.
Images that uploaded but still look broken
If the file opens fine by its direct link but not on the page:
- The link is
http://while the site ishttps://, so the browser blocks it as mixed content. See Images or API calls blocked on your live site? Check for http:// links. - Capital letters differ between the stored path and the path in your code (
Photo.JPGvsphoto.jpg). Storage paths are exact. See Images broken only on the live site? Check the capital letters. - The project is paused. Free projects pause after a period of inactivity, and every file request fails until you restore it. See Site loads but data is gone? Your free backend may be paused.
How to confirm it's fixed
- Upload as a fresh test user in a private window, on a phone as well as a laptop.
- Check the Network tab: the storage request should return 200.
- Reload the page and confirm the image or file shows, then open its link while signed out. Public files should open; private ones should not.
Upload bugs are easy to miss because you test with your own account. The free 30-second health check shows which pages and images on your live site fail to load. For ongoing coverage, FlowCanary offers Daily monitoring of your signup, login and checkout (in development; founding spots $19/month, price locked for life, full refund on request any time before it launches).
