CORS Configuration Setup

Configure Cross-Origin Resource Sharing (CORS) for your storage provider to enable large file uploads

⚠️ IMPORTANT NOTICE - CORS Configuration Required

You MUST configure CORS settings on your storage bucket before uploading files larger than 10MB.Without proper CORS configuration, you will encounter the following errors:

Error 1: CORS policy error

"Access to XMLHttpRequest at 'https://your-bucket.s3.amazonaws.com/your-file' from origin 'https://your-website.com' has been blocked by CORS policy."

Error 2: Preflight request failure

"OPTIONS https://your-bucket.s3.amazonaws.com/your-file 403 (Forbidden)"

These errors will prevent successful file uploads and cause upload failures. Configure CORS now to avoid these issues.

Supported Storage Providers

CORS Supported

Amazon S3✅
Cloudflare R2✅
Google Cloud Storage✅
Microsoft Azure Blob✅
DigitalOcean Spaces✅
Wasabi Cloud Storage✅
MinIO✅
Firebase Storage✅
Oracle Cloud Object Storage✅

Limited CORS Support

Backblaze B2❌

These providers don't support direct browser uploads. Use server-side uploads only.

Required CORS Configuration (@cors.json)

📁 Create cors.json File

Create a file named cors.json in your project root with the following content:

This configuration allows all origins to perform file operations with proper headers for multipart uploads.

Development/Testing Configuration (allows all origins):

[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 3000
  }
]

🔧 Configuration Explanation

AllowedOrigins: ["*"] allows requests from any domain
AllowedMethods: Required methods for multipart uploads
AllowedHeaders: ["*"] permits all headers including custom ones
ExposeHeaders: ["ETag"] is critical for multipart upload completion
MaxAgeSeconds: 3000 caches preflight requests for 50 minutes

Production Configuration (restrict to your domains):

[
  {
    "AllowedOrigins": [
      "https://yourdomain.com",
      "https://www.yourdomain.com"
    ],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag", "x-amz-version-id"],
    "MaxAgeSeconds": 3000
  }
]

Quick Setup Commands

S3-Compatible Services (S3, R2, DigitalOcean, Wasabi)

aws s3api put-bucket-cors \
  --bucket YOUR_BUCKET_NAME \
  --cors-configuration file://cors.json \
  --endpoint-url YOUR_ENDPOINT_URL

MinIO (Self-Hosted) - Using MinIO Client

# Install MinIO Client
curl https://dl.min.io/client/mc/release/linux-amd64/mc -o mc
chmod +x mc && sudo mv mc /usr/local/bin/

# Configure alias
mc alias set myminio http://your-minio-server:9000 ACCESS_KEY SECRET_KEY

# Apply CORS (uses cors-minio.json)
mc admin config set myminio/ cors-minio.json

Google Cloud Storage

gsutil cors set cors.json gs://YOUR_BUCKET_NAME

Microsoft Azure Blob Storage

az storage cors add \
  --services b \
  --methods GET PUT POST DELETE HEAD \
  --origins "*" \
  --allowed-headers "*" \
  --exposed-headers "ETag" \
  --max-age 3000

Troubleshooting

Common Issues:

Preflight request fails - ensure all methods are allowed
ETag not available - add "ETag" to ExposeHeaders
Upload fails - verify PUT method is allowed

Testing CORS:

Open browser developer tools (F12)
Go to Network tab
Attempt a file upload
Check for CORS errors in console

Next Steps

1. Configure CORS for your storage provider

2. Test with a small file upload

3. Try uploading a large file (>10MB) to test multipart uploads

4. Check the detailed storage providers guide for specific instructions