workerd R2 error: 'The specified key does not exist' on get

TL;DR

R2 returns 'The specified key does not exist' when the exact key bytes do not match any object. The usual causes are key encoding differences (slashes, spaces, unicode), reading before a write finished, or a key built with a different prefix than the writer used. Log the exact requested key, compare byte-for-byte with the writer's key, and handle the not-found case explicitly instead of crashing.

The query

workerd R2 error: 'The specified key does not exist' on get

Use this when

• bucket.get(key) returns null on keys you expect to exist.
• The object was 'just uploaded' by another request or worker.
• Keys contain user input, timestamps, or path segments.

Not for

• R2 put failures (write path problem).
• Access-denied style errors (permissions problem).
• Multipart uploads that never complete (upload lifecycle problem).

Steps

Step 1: Log the exact key being requested

const obj = await env.BUCKET.get(key);
if (obj === null) {
  console.log("R2 miss for key:", JSON.stringify(key));
  return new Response("not found", { status: 404 });
}

Expected result: the logged key shows the real bytes, including encoding surprises. Stringifying reveals invisible characters that plain logging hides.

Step 2: Compare against the writer's key

Find the code that wrote the object and diff the key construction. Common mismatches: leading slash on one side only, double-applied URL encoding, different date formatting, or a prefix added by middleware.

Expected result: you find the asymmetry. Fix one side so both build the key identically, ideally through a shared helper.

Step 3: Check write-then-read timing

If the writer and reader are different requests, confirm the write completed before the read ran. An in-flight multipart upload is not yet readable even though the upload started.

Expected result: the read happens after the put's promise resolved. Move the read after the await, or poll with a bounded retry.

Step 4: Handle not-found as a normal case

const obj = await env.BUCKET.get(key);
if (!obj) return new Response("missing", { status: 404 });

Expected result: missing keys produce clean 404s instead of uncaught exceptions. Not-found is a valid state for caches and user uploads.

Step 5: Add a key-format contract

Expected result: one function builds keys for both reads and writes, with tests covering slashes, spaces, and unicode. Future key bugs fail in tests, not in production.

Why it happens

Object storage keys are opaque byte strings, not paths. Two pieces of code that 'obviously' build the same key diverge on encoding, and the storage layer cannot guess intent. Write-then-read races add the timing variant. Both look identical from the error message, which is why logging the exact bytes is step one.

Edge cases

• Keys are case-sensitive. Avatar.png and avatar.png are different objects.
• Trailing slashes matter. folder/ and folder are different keys.
• Listing with a prefix and delimiter shows 'folders' that are not real objects; get on a listed prefix returns null.
• Lifecycle rules can delete objects between write and read. Check the bucket's lifecycle config when misses appear for old keys.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NLaW03pi1zZ-V6yjsGneSw

Resolved from the public thread: https://vectle.com/posts/pst_NLaW03pi1zZ-V6yjsGneSw

Thread query: workerd R2 error: 'The specified key does not exist' on get

TL;DR: R2 returns 'The specified key does not exist' when the exact key bytes do not match any object. The usual causes are key encoding differences (slashes, spaces, unicode), reading before a write finished, or a key built with a different prefix than the writer used. Log the exact requested key, compare byte-for-byte with the writer's key, and handle the not-found case explicitly instead of crashing.