NoSuchKey
Amazon S3 NoSuchKey means the bucket exists, but the exact object key requested does not resolve to a current object.
Last reviewed: April 24, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does No Such Key Mean?
S3 found the bucket, then failed the object lookup. The useful boundary is exact key identity: prefix, delimiter, casing, encoding, version/delete-marker state, and whether the producer actually wrote the object that the consumer is trying to read.
Common Causes
- -Producer and consumer build different object keys because prefix, delimiter, extension, or tenant path logic diverged.
- -Key casing differs from the uploaded object because S3 object keys are case-sensitive.
- -URL encoding or decoding changes spaces, plus signs, percent escapes, or unicode characters in key names.
- -The object was deleted, overwritten, expired by lifecycle policy, or hidden by a current delete marker.
- -A reader starts before the producer has committed the object or before replication/copy workflow reaches the expected destination.
How to Fix No Such Key
- 1Confirm the bucket exists first, then list the expected prefix and compare the exact returned key byte-for-byte.
- 2Trace the key emitted by the producer at write time and the key requested by the consumer at read time.
- 3Normalize key construction through one shared builder so upload, event, CDN, and download paths agree.
- 4Check versioning, delete markers, lifecycle expiration, and replication or copy status before regenerating data.
- 5If the requested key was never produced, fix the producer contract or update the stored canonical reference.
Step-by-Step Diagnosis for No Such Key
- 1Capture bucket, full key, request ID, caller, and operation type from the failing
GetObjectorHeadObjectcall. - 2Run
ListObjectsV2on the nearest stable prefix and look for casing, delimiter, extension, and encoding near-matches. - 3Compare the canonical key stored in producer metadata, event payloads, or database rows with the runtime read key.
- 4Inspect versioning and lifecycle events for delete markers, expiration, overwrite, or transition behavior around the incident window.
- 5Re-test using the exact listed key and then the application-generated key to isolate key construction from storage state.
Seen in Production
- -An image pipeline writes
images/original/..., but the frontend requestsimages/optimized/...before the transform job creates that object. - -A report writer stores
reports/2026/summary.JSON, while a reader requestsreports/2026/summary.jsonand gets NoSuchKey. - -A file named
report 2026.csvis stored with a literal space, but a downstream URL builder requestsreport+2026.csv. - -A lifecycle rule creates a delete marker for the current version, so normal reads return missing even though historical versions still exist.
Object Key Path Verification
- -Trace key construction end to end, including prefix, delimiter, extension, casing, and tenant or date partition fields.
- -Inspect URL-encoding normalization between producer and consumer (example: writer stores
%20, reader requests+for spaces).
Lifecycle, Version, and Producer Timing
- -Audit lifecycle transitions, delete markers, and overwrites for the requested key.
- -Verify read-after-write sequencing and replication timing (example: consumer fetches key before ingest pipeline commits or copies the object).
Decision Shortcut: Missing Object vs Missing Bucket
- -If
head-bucketfails, move back to NoSuchBucket before debugging object paths. - -If
ListObjectsV2shows a near-match, stay on key construction, casing, or encoding. - -If the key existed and then disappeared, inspect lifecycle, overwrite, delete-marker, and retention paths before changing producers.
Wrong Fix to Avoid
- -Do not recreate buckets or widen S3 permissions when the bucket exists and only the object key is missing.
- -Do not retry the same read forever if the producer never wrote the object under that exact key.
- -Do not hand-normalize URL encoding in one consumer while other readers still use a different key builder.
Implementation Examples
2026-04-24T10:42:18Z bucket=media-prod requestedKey=images/optimized/u/42/avatar.jpg
producerKey=images/original/u/42/avatar.jpg status=404 error=NoSuchKey
message="The specified key does not exist."aws s3api list-objects-v2 \
--bucket media-prod \
--prefix 'images/' \
--query 'Contents[].Key'const objectKey = uploadEvent.objectKey;
await s3.send(new GetObjectCommand({
Bucket: 'media-prod',
Key: objectKey,
}));Incident Timeline
10:41 UTC
A consumer requests an object key derived from stale or divergent logic
Signal: The read path emits a key that differs from the producer key by prefix, casing, delimiter, encoding, or generation stage.
Why it matters: The first useful question is whether this exact key was ever written.
10:42 UTC
S3 resolves the bucket but returns NoSuchKey
Signal: Bucket lookup succeeds, object lookup fails, and downstream render, download, or batch processing breaks.
Why it matters: The incident is now object-key identity, not bucket identity.
10:44 UTC
Retries repeat the same absent key
Signal: Clients keep requesting the same generated key and receive deterministic 404 responses.
Why it matters: Retries do not help until producer output, canonical metadata, or key construction is corrected.
10:52 UTC
The canonical key is restored or generated
Signal: The requested object is produced, the stored key reference is corrected, or consumers switch to the exact key emitted by the producer.
Why it matters: That confirms the failure lived in key resolution or object lifecycle, not S3 availability.
Seen in Production
Frontend requests transformed image key that was never generated
Frequency: common
Example: An image pipeline stores images/original/... but UI requests images/optimized/... without fallback.
Fix: Align key conventions across pipeline stages and add existence checks before publishing URLs.
Object key includes spaces that are encoded differently by two services
Frequency: medium
Example: Uploader writes report 2026.csv, reader requests report+2026.csv and receives NoSuchKey.
Fix: Standardize URL encoding/decoding and validate canonical keys at API boundaries.
Lifecycle rule creates a delete marker for the current object version
Frequency: rare
Example: Historical versions exist, but normal reads fail because the current version is a delete marker.
Fix: Inspect version history and adjust lifecycle or restore the intended current object version.
Wrong Fix vs Better Fix
Retry same key vs prove producer output
Wrong fix: Replay the same GetObject call and wait for it to eventually work.
Better fix: Find the producer event or metadata row that should contain the canonical key, then compare it to the read key.
Why this is better: NoSuchKey is deterministic unless the object is later created or the requested key changes.
Patch one consumer vs centralize key building
Wrong fix: Fix casing or encoding in one reader path only.
Better fix: Move key construction into a shared builder or store the canonical key from the write event.
Why this is better: S3 key bugs recur when each service independently reconstructs object paths.
Ignore versioning vs inspect delete markers
Wrong fix: Assume the object never existed because the current read returns missing.
Better fix: Check versioning, delete markers, overwrite events, and lifecycle rules around the failure window.
Why this is better: A missing current version can hide a lifecycle or deletion incident rather than a producer miss.
Debugging Tools
- -aws s3api list-objects-v2
- -aws s3api head-object --debug
- -CloudTrail data events for S3
- -Object key generation logs
How to Verify the Fix
- -Repeat the failing
GetObjectorHeadObjectcall and confirm the exact requested key now returns successfully. - -Validate downstream parsing, rendering, or batch jobs consume the returned object correctly.
- -Confirm NoSuchKey error rates drop in application, CDN, and S3 data-event logs.
- -Verify producers and consumers now emit the same canonical key for representative edge-case names.
How to Prevent Recurrence
- -Use a shared key-builder library across all services that write/read the same objects.
- -Store canonical object keys in metadata or events instead of rebuilding them ad hoc.
- -Alert on unexpected object deletions, delete markers, and lifecycle-rule mismatches in critical prefixes.
- -Add fixture tests for spaces, plus signs, unicode, casing, and tenant/date prefixes.
Pro Tip
- -persist the authoritative key emitted at write time (event payload/metadata) and consume that exact key in downstream readers.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.