Gotchas & Best Practices
Fit Modes
| Mode | Best For | Behavior |
|---|---|---|
cover |
Hero images, thumbnails | Fills space, crops excess |
contain |
Product images, artwork | Preserves full image, may add padding |
scale-down |
User uploads | Never enlarges |
crop |
Precise crops | Uses gravity |
pad |
Fixed aspect ratio | Adds background |
Format Selection
format: 'auto' // Recommended - negotiates best formatSupport: AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)
Quality Settings
| Use Case | Quality |
|---|---|
| Thumbnails | 75-80 |
| Standard | 85 (default) |
| High-quality | 90-95 |
Common Errors
5403: "Image transformation failed"
- Verify
width/height≤ 12000 - Check
quality1-100,dpr1-3 - Don't combine incompatible options
9413: "Rate limit exceeded"
Implement caching and exponential backoff:
for (let i = 0; i < 3; i++) {
try { return await env.IMAGES.input(buffer).transform({...}).output(); }
catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }
}5401: "Image too large"
Pre-process images before upload (max 100MB, 12000×12000px)
5400: "Invalid image format"
Supported: JPEG, PNG, GIF, WebP, AVIF, SVG
401/403: "Unauthorized"
Verify API token has Cloudflare Images → Edit permission
Limits
| Resource | Limit |
|---|---|
| Max input size | 100MB |
| Max dimensions | 12000×12000px |
| Quality range | 1-100 |
| DPR range | 1-3 |
| API rate limit | ~1200 req/min |
AVIF Gotchas
- Slower encoding: First request may have higher latency
- Browser detection:
const format = /image\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';Anti-Patterns
// ❌ No caching - transforms every request
return env.IMAGES.input(buffer).transform({...}).output().response();
// ❌ cover without both dimensions
transform({ width: 800, fit: 'cover' })
// ✅ Always set both for cover
transform({ width: 800, height: 600, fit: 'cover' })
// ❌ Exposes API token to client
// ✅ Use Direct Creator Upload (patterns.md)Debugging
// Check response headers
console.log('Content-Type:', response.headers.get('Content-Type'));
// Test with curl
// curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif"
// Monitor logs
// npx wrangler tail