MIME Type Detection Reference

Complete documentation of r2put's automatic MIME type detection.

Overview

r2put automatically detects content types from file extensions. The detected MIME type is used when uploading files to R2.

Supported MIME Types

Detection Behavior

Extension Matching

• Case-Insensitive: Extension matching is case-insensitive
  • .JPG, .jpg, .Jpg all map to image/jpeg
• Last Extension: Uses last extension if multiple extensions
  • file.tar.gz → application/gzip (from .gz)
  • archive.backup.tar → application/x-tar (from .tar)

Fallback Behavior

• Unknown Extensions: Falls back to application/octet-stream
• No Extension: Falls back to application/octet-stream
• Content-Based Detection: Not supported (extension-only)

Examples

Basic Detection

# Image files
r2put --file ./image.jpg --bucket my-bucket
# Detects: image/jpeg

r2put --file ./photo.png --bucket my-bucket
# Detects: image/png

# Document files
r2put --file ./document.pdf --bucket my-bucket
# Detects: application/pdf

r2put --file ./data.json --bucket my-bucket
# Detects: application/json

Case Variations

# Case-insensitive matching
r2put --file ./IMAGE.JPG --bucket my-bucket
# Detects: image/jpeg

r2put --file ./Photo.Png --bucket my-bucket
# Detects: image/png

Multiple Extensions

# Uses last extension
r2put --file ./archive.tar.gz --bucket my-bucket
# Detects: application/gzip (from .gz)

r2put --file ./backup.old.tar --bucket my-bucket
# Detects: application/x-tar (from .tar)

Unknown Extensions

# Unknown extension falls back to application/octet-stream
r2put --file ./data.unknown --bucket my-bucket
# Detects: application/octet-stream

# No extension falls back to application/octet-stream
r2put --file ./data --bucket my-bucket
# Detects: application/octet-stream

Limitations

Extension-Only Detection

r2put uses extension-based detection only. It does not:

• Analyze file content
• Use magic number detection
• Check file headers
• Perform content-based MIME type detection

Custom MIME Types

r2put does not support:

• Custom MIME type specification
• Overriding detected MIME type
• Per-file MIME type configuration

Workarounds

Using @cfkit/r2 Directly

For specific MIME type control, use @cfkit/r2 directly:

import { R2 } from '@cfkit/r2';

const r2 = new R2({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
});

await r2.putObject({
  bucket: 'my-bucket',
  key: 'file.bin',
  body: fileContent,
  contentType: 'application/custom-type', // Custom MIME type
});

File Renaming

Rename files to use recognized extensions:

# Rename file to use recognized extension
mv data.custom data.bin
r2put --file ./data.bin --bucket my-bucket
# Detects: application/octet-stream

Best Practices

1. Use Standard Extensions: Use standard file extensions for accurate detection
2. Verify Detection: Check detected MIME type in terminal UI output
3. Custom Types: Use @cfkit/r2 directly for custom MIME types
4. Extension Consistency: Maintain consistent extension usage

Troubleshooting

MIME Type Detection Incorrect

Symptoms:

• Detected MIME type doesn't match expected type
• File served with wrong content type

Resolution:

• Verify file extension matches expected type
• Check extension is in supported list
• Use @cfkit/r2 directly to set specific MIME type
• Rename file to use recognized extension

Unknown Extension

Symptoms:

• File detected as application/octet-stream
• Extension not recognized

Resolution:

• Extension not in supported list (expected behavior)
• Falls back to application/octet-stream
• Use @cfkit/r2 directly for custom MIME types
• Rename file to use recognized extension if appropriate