Upload Troubleshooting Guide

Problem

Uploads work locally but fail in production.

Most Likely Issues & Solutions

Issue 1: CORS Configuration (MOST COMMON)

Symptom: Browser console shows CORS policy blocked... error

Solution:

1. Go to your project Dashboard
2. Navigate to Storage → Configuration (or Policies & Settings)
3. Look for CORS Configuration or Allowed Origins
4. Add your production domains

Issue 2: Authentication Token Not Sent

Symptom: 401 Unauthorized or upload fails silently

Check:

1. Open browser DevTools → Network tab
2. Filter by your bucket name
3. Check the request headers for:
   • Authorization: Bearer <token>
   • apikey: <anon-key>

Fix: Ensure the client is properly initialized with the production URL and keys.

Issue 3: RLS Policy Failure

Symptom: 403 Forbidden error

Verify RLS Policies:

• Policy checks that bucket_id matches
• Policy checks that path starts with auth.uid()

Issue 4: File Size Limits

Check bucket limits:

• Default limits are typically 10MB
• Frontend limits may differ

Solution: Reduce file size or increase bucket limit in settings.

Issue 5: MIME Type Mismatch

Symptom: 422 Unprocessable Entity or "Invalid file type" error

Supported types:

• Images: JPEG, JPG, PNG, GIF, WebP, HEIC, HEIF
• Audio: MPEG (MP3), WebM, WAV, M4A, MP4, OGG

Debugging Steps

1. Check Browser Console

Open DevTools Console and check for:

• CORS errors
• 401/403/422 status codes
• Network request failures

2. Inspect Network Request

1. Open DevTools → Network tab
2. Try uploading a file
3. Find the failed request
4. Check:
   • Request URL
   • Request Headers (Authorization, apikey)
   • Request Payload
   • Response Status
   • Response Body

3. Check Logs

In your Dashboard → Logs → Storage Logs:

• Filter for errors related to uploads
• Look for specific error messages

Common Error Messages

Error	Meaning	Solution
CORS policy: No 'Access-Control-Allow-Origin'	CORS not configured	Add production domain to CORS allowed origins
401 Unauthorized	Auth token missing/invalid	Check client initialization
403 Forbidden	RLS policy blocked	Verify user is authenticated and path is correct
413 Payload Too Large	File too big	Reduce file size or increase bucket limit
422 Unprocessable Entity	MIME type not allowed	Check supported file types

Quick Test

Create a test upload:

1. Deploy the latest code to production
2. Log in to production app
3. Try uploading a small PNG image (< 1MB)
4. Check browser console for any errors
5. Report the exact error message

Next Steps

1. Configure CORS (most likely fix)
2. Test upload in production
3. Share specific error from browser console if still failing
4. Check dashboard Storage logs for more details