R2 CORS Debugger

Systematically diagnose and fix CORS (Cross-Origin Resource Sharing) configuration issues for R2 buckets.

Required Information

1. Bucket name: {{bucket_name}}
2. Origin domain (e.g., https://example.com): {{origin}}
3. Methods needed (e.g., GET, PUT, POST, DELETE): {{methods}}
4. Error message (from browser console, if any): {{error_message}}

What This Command Does

1. Checks current CORS policy on bucket
2. Generates correct CORS configuration for your use case
3. Provides curl test commands to verify setup
4. Shows Dashboard configuration steps
5. Explains common CORS pitfalls

Common CORS Errors

Error Message	Cause	Fix
"No 'Access-Control-Allow-Origin' header"	Missing origin in AllowedOrigins	Add your domain
"Method PUT is not allowed"	Method not in AllowedMethods	Add PUT to allowed methods
"Header 'Content-Type' not allowed"	Header not in AllowedHeaders	Add Content-Type
"Credentials mode requires specific origin"	Using wildcard with credentials	Use specific origin

CORS Configuration Template

[
  {
    "AllowedOrigins": [
      "https://example.com",
      "https://www.example.com"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE"
    ],
    "AllowedHeaders": [
      "Content-Type",
      "Authorization",
      "X-Requested-With"
    ],
    "ExposeHeaders": [
      "ETag",
      "Content-Length"
    ],
    "MaxAgeSeconds": 3600
  }
]

Dashboard Configuration Steps

1. Navigate to R2 → Select your bucket
2. Click Settings tab
3. Scroll to CORS Policy section
4. Click Edit CORS policy
5. Paste JSON configuration
6. Click Save

Testing CORS with curl

# Test preflight request (OPTIONS)
curl -v \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: PUT" \
  -H "Access-Control-Request-Headers: Content-Type" \
  -X OPTIONS \
  "https://{{bucket_name}}.{{account_id}}.r2.cloudflarestorage.com/test.txt"

# Expected response headers:
# Access-Control-Allow-Origin: https://example.com
# Access-Control-Allow-Methods: GET, PUT, POST, DELETE
# Access-Control-Allow-Headers: Content-Type
# Access-Control-Max-Age: 3600

# Test actual request (PUT)
curl -v \
  -H "Origin: https://example.com" \
  -H "Content-Type: text/plain" \
  -X PUT \
  "https://{{bucket_name}}.{{account_id}}.r2.cloudflarestorage.com/test.txt" \
  -d "Test data"

# Expected response headers:
# Access-Control-Allow-Origin: https://example.com
# Access-Control-Expose-Headers: ETag

Common Use Cases

Browser Upload

{
  "AllowedOrigins": ["https://myapp.com"],
  "AllowedMethods": ["PUT", "POST"],
  "AllowedHeaders": ["Content-Type"],
  "MaxAgeSeconds": 3600
}

Browser Download

{
  "AllowedOrigins": ["https://myapp.com"],
  "AllowedMethods": ["GET", "HEAD"],
  "AllowedHeaders": ["Range"],
  "ExposeHeaders": ["ETag", "Content-Length", "Content-Range"],
  "MaxAgeSeconds": 3600
}

Full Access (Development)

{
  "AllowedOrigins": ["http://localhost:3000"],
  "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
  "AllowedHeaders": ["*"],
  "MaxAgeSeconds": 3600
}

Security Best Practices

1. Never use wildcard (*) in production - Specify exact origins
2. Limit methods - Only allow methods you actually need
3. HTTPS only in production - Don't allow HTTP origins
4. Set reasonable MaxAgeSeconds - 3600 (1 hour) is good default
5. Don't expose unnecessary headers - Limit ExposeHeaders
6. Test after changes - Always verify CORS works before deploying

Troubleshooting Checklist

• CORS policy configured on R2 bucket (not just Worker)
• Origin matches exactly (including protocol and port)
• All required methods are in AllowedMethods
• All custom headers are in AllowedHeaders
• Browser is sending preflight OPTIONS request
• Bucket name and account ID are correct in URL
• Testing with actual browser (not just curl)
• Clear browser cache if policy was recently changed