SupabaseStorage

Supabase Storage: Bucket not found

StorageApiError: Bucket not found

In short: The Storage API cannot find a bucket with that exact name in the project this app is talking to, or the file URL you are using does not work for a private bucket.

Why it happens

Bucket names are case-sensitive and must already exist in the same Supabase project as the URL and anon (or service) key in your env. AI tools often hard-code avatars or uploads and never create the bucket, or they create it in a different project than the one in .env. A second, related failure: the upload succeeds on a private bucket, then the UI uses getPublicUrl, which only works for public buckets, so the image 400s or looks missing. Uploads can also fail with an RLS error on storage.objects if the bucket has policies that do not allow this user to insert or select that path.

How to fix it

1. In Supabase → Storage, confirm a bucket exists whose name matches the string in your code letter for letter (Avatars and avatars are different). Create it if it is missing, and note whether it is public or private.
2. Confirm the app's SUPABASE_URL / VITE_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_URL points at that same project. A key from project A and a bucket in project B produces Bucket not found.
3. For a public bucket, getPublicUrl('folder/file.png') is fine once the object exists. For a private bucket, use createSignedUrl (short-lived) or a server-side download with the user's session. Don't switch the bucket to public just so a public URL works.
4. If the error is a policy violation on upload or read, open Storage → the bucket → Policies (these are RLS policies on storage.objects). A typical user-upload policy allows authenticated to insert and select only when auth.uid() matches the first folder in the object name, for example avatars/USER_ID/avatar.png.
5. Retry one upload from a signed-in session and log error.message from the Storage call, not only a failed <img> in the page.

Example

const { data, error } = await supabase.storage
  .from("avatars")
  .createSignedUrl(`${user.id}/avatar.png`, 60 * 60);
if (error) throw error;
// data.signedUrl  — use this for a private bucket, not getPublicUrl()

Copy-paste fix prompt

I'm getting this error in my app:

StorageApiError: Bucket not found

[Paste the full error, stack trace, and the file it points to here]

Likely cause: The Storage API cannot find a bucket with that exact name in the project this app is talking to, or the file URL you are using does not work for a private bucket.

Task: Storage returns Bucket not found, or the file uploaded but the image URL fails. Check the bucket name and project URL match, then use getPublicUrl only for public buckets and createSignedUrl for private ones. Add storage.objects policies scoped to auth.uid() if uploads or reads are denied. Don't expose the service-role key or open the bucket to the world.

Rules:
- First explain the root cause in 2 sentences and list the files you'll change.
- Make the smallest change that fixes it. Don't refactor unrelated code.
- Don't disable security or checks (RLS, auth, signature verification, type checking, CORS allow-all) to make the error disappear.
- Never print or hard-code secret keys.
- Finish by telling me exactly how to verify the fix.

Common with: Lovable, Bolt, Cursor, v0. Last reviewed 2026-11-15.