1# R2 Gotchas & Troubleshooting
2 
3## List Truncation
4 
5```typescript
6// ❌ WRONG: Don't compare object count when using include
7while (listed.objects.length < options.limit) { ... }
8 
9// ✅ CORRECT: Always use truncated property
10while (listed.truncated) {
11  const next = await env.MY_BUCKET.list({ cursor: listed.cursor });
12  // ...
13}
14```
15 
16**Reason:** `include` with metadata may return fewer objects per page to fit metadata.
17 
18## ETag Format
19 
20```typescript
21// ❌ WRONG: Using etag (unquoted) in headers
22headers.set('etag', object.etag); // Missing quotes
23 
24// ✅ CORRECT: Use httpEtag (quoted)
25headers.set('etag', object.httpEtag);
26```
27 
28## Checksum Limits
29 
30Only ONE checksum algorithm allowed per PUT:
31 
32```typescript
33// ❌ WRONG: Multiple checksums
34await env.MY_BUCKET.put(key, data, { md5: hash1, sha256: hash2 }); // Error
35 
36// ✅ CORRECT: Pick one
37await env.MY_BUCKET.put(key, data, { sha256: hash });
38```
39 
40## Multipart Requirements
41 
42- All parts must be uniform size (except last part)
43- Part numbers start at 1 (not 0)
44- Uncompleted uploads auto-abort after 7 days
45- `resumeMultipartUpload` doesn't validate uploadId existence
46 
47## Conditional Operations
48 
49```typescript
50// Precondition failure returns object WITHOUT body
51const object = await env.MY_BUCKET.get(key, {
52  onlyIf: { etagMatches: '"wrong"' }
53});
54 
55// Check for body, not just null
56if (!object) return new Response('Not found', { status: 404 });
57if (!object.body) return new Response(null, { status: 304 }); // Precondition failed
58```
59 
60## Key Validation
61 
62```typescript
63// ❌ DANGEROUS: Path traversal
64const key = url.pathname.slice(1); // Could be ../../../etc/passwd
65await env.MY_BUCKET.get(key);
66 
67// ✅ SAFE: Validate keys
68if (!key || key.includes('..') || key.startsWith('/')) {
69  return new Response('Invalid key', { status: 400 });
70}
71```
72 
73## Storage Class Pitfalls
74 
75- InfrequentAccess: 30-day minimum billing (even if deleted early)
76- Can't transition IA → Standard via lifecycle (use S3 CopyObject)
77- Retrieval fees apply for IA reads
78 
79## Stream Length Requirement
80 
81```typescript
82// ❌ WRONG: Streaming unknown length fails silently
83const response = await fetch(url);
84await env.MY_BUCKET.put(key, response.body); // May fail without error
85 
86// ✅ CORRECT: Buffer or use Content-Length
87const data = await response.arrayBuffer();
88await env.MY_BUCKET.put(key, data);
89 
90// OR: Pass Content-Length if known
91const object = await env.MY_BUCKET.put(key, request.body, {
92  httpMetadata: {
93    contentLength: parseInt(request.headers.get('content-length') || '0')
94  }
95});
96```
97 
98**Reason:** R2 requires known length for streams. Unknown length may cause silent truncation.
99 
100## S3 SDK Region Configuration
101 
102```typescript
103// ❌ WRONG: Missing region breaks ALL S3 SDK calls
104const s3 = new S3Client({
105  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
106  credentials: { ... }
107});
108 
109// ✅ CORRECT: MUST set region='auto'
110const s3 = new S3Client({
111  region: 'auto', // REQUIRED
112  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
113  credentials: { ... }
114});
115```
116 
117**Reason:** S3 SDK requires region. R2 uses 'auto' as placeholder.
118 
119## Local Development Limits
120 
121```typescript
122// ❌ Miniflare/wrangler dev: Limited R2 support
123// - No multipart uploads
124// - No presigned URLs (requires S3 SDK + network)
125// - Memory-backed storage (lost on restart)
126 
127// ✅ Use remote bindings for full features
128wrangler dev --remote
129 
130// OR: Conditional logic
131if (env.ENVIRONMENT === 'development') {
132  // Fallback for local dev
133} else {
134  // Full R2 features
135}
136```
137 
138## Presigned URL Expiry
139 
140```typescript
141// ❌ WRONG: URL expires but no client validation
142const url = await getSignedUrl(s3, command, { expiresIn: 60 });
143// 61 seconds later: 403 Forbidden
144 
145// ✅ CORRECT: Return expiry to client
146return Response.json({
147  uploadUrl: url,
148  expiresAt: new Date(Date.now() + 60000).toISOString()
149});
150```
151 
152## Limits
153 
154| Limit | Value |
155|-------|-------|
156| Object size | 5 TB |
157| Multipart part count | 10,000 |
158| Multipart part min size | 5 MB (except last) |
159| Batch delete | 1,000 keys |
160| List limit | 1,000 per request |
161| Key size | 1024 bytes |
162| Custom metadata | 2 KB per object |
163| Presigned URL max expiry | 7 days |
164 
165## Common Errors
166 
167### "Stream upload failed" / Silent Truncation
168 
169**Cause:** Stream length unknown or Content-Length missing  
170**Solution:** Buffer data or pass explicit Content-Length
171 
172### "Invalid credentials" / S3 SDK
173 
174**Cause:** Missing `region: 'auto'` in S3Client config  
175**Solution:** Always set `region: 'auto'` for R2
176 
177### "Object not found"
178 
179**Cause:** Object key doesn't exist or was deleted  
180**Solution:** Verify object key correct, check if object was deleted, ensure bucket correct
181 
182### "List compatibility error"
183 
184**Cause:** Missing or old compatibility_date, or flag not enabled  
185**Solution:** Set `compatibility_date >= 2022-08-04` or enable `r2_list_honor_include` flag
186 
187### "Multipart upload failed"
188 
189**Cause:** Part sizes not uniform or incorrect part number  
190**Solution:** Ensure uniform size except final part, verify part numbers start at 1
191