references/r2/gotchas.md
R2 Gotchas & Troubleshooting
Use the current references to diagnose the actual response or error instead of copying a workaround.
| Symptom or decision | What to check |
|---------------------|---------------|
| Listing stops early or escapes the intended prefix | Follow truncated and the returned cursor, retaining the original prefix, delimiter, and metadata options on subsequent requests. See the listing section of the Workers API reference. |
| Conditional read has no body, or conditional write returns null | Distinguish a missing object from a failed condition; choose the HTTP response for the actual request condition. See conditional operations in the Workers API reference. |
| ETag, metadata, checksum, or stream upload behaves unexpectedly | Check supported values and return types in the Workers API reference, the Worker upload example, and Workers streams. |
| Multipart upload fails or cannot be resumed | Check part constraints and handle an upload that has already completed or aborted: multipart guide and API reference. |
| S3 authentication or signed URL fails | Verify credentials, endpoint, region, operation, signed headers, and expiry using SDK setup, authentication, and presigned URLs. |
| Browser fails but an HTTP client succeeds | Check CORS and troubleshooting. |
| Local and deployed data or behavior differ | Check local development, supported bindings, and the local persistence options in Wrangler R2 commands. |
| Reads serve old or missing content after an update | Check the consistency model and cache interactions. |
| Upload size, metadata size, storage cost, or lifecycle behavior is unexpected | Fetch limits, pricing, storage classes, and object lifecycles. |
For other failures, start with R2 troubleshooting and error codes.