PreconditionFailed
Amazon S3 PreconditionFailed means a conditional request reached the object but one of its current-state guards evaluated false.
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 Precondition Failed Mean?
S3 accepted the target bucket/key lookup, then rejected the operation because the condition supplied by the client did not match current object state. This usually protects optimistic concurrency, create-if-absent flows, cache validation, or range/copy safety; the fix is to refresh state and rebuild the request intentionally.
Common Causes
- -
If-Matchcarries an ETag from an older object version after another writer updated or replaced the key. - -
If-None-Match: *is used for create-if-absent, but an object already exists at the key. - -
If-Unmodified-SinceorIf-Modified-Sinceuses a stale or imprecise timestamp compared with current object metadata. - -Copy, multipart, or range workflows reuse validators after the source object changed.
- -Parallel Lambda jobs, queue workers, or users update the same S3-backed manifest without ordered write control.
How to Fix Precondition Failed
- 1Call
HeadObjectand refresh ETag, Last-Modified, version ID, and object size before retrying. - 2Match the conditional header to intent:
If-Matchfor guarded overwrite,If-None-Match: *for create-if-absent, and timestamp validators for freshness-sensitive reads. - 3Re-read and rebase the intended mutation instead of replaying the stale conditional write.
- 4Serialize or partition hot-key writers where repeated PreconditionFailed reflects real contention.
- 5Keep the condition when it protects correctness; only remove it when a blind overwrite is explicitly safe.
Step-by-Step Diagnosis for Precondition Failed
- 1Capture bucket, key, operation, conditional headers, request ID, and caller identity from the failing request.
- 2Compare supplied validators with current
HeadObjectoutput, including ETag, Last-Modified, version ID, and content length. - 3Trace concurrent
PutObject,CopyObject, multipart complete, delete, or restore workflows for the same key. - 4Determine whether the failure is guarded overwrite, create-if-absent conflict, cache validation, copy precondition, or range safety.
- 5Retest with a read-refresh-rebase-write cycle and confirm stale validators still fail safely.
Seen in Production
- -Two Lambda workers update the same JSON manifest; the second sends a stale
If-Matchand receives PreconditionFailed. - -An upload path uses
If-None-Match: *to protect create-if-absent, but a retry finds that the first attempt already created the key. - -A copy job validates a source ETag, then fails because a newer artifact replaced the source object before copy starts.
- -A range downloader pins an old ETag while the object is replaced, so S3 rejects the conditional range request.
Conditional Header and Object Validator Audit
- -Compare request validators against
HeadObjectoutput for the exact bucket/key/version. - -Inspect whether
If-Match,If-None-Match,If-Modified-Since, orIf-Unmodified-Sincematches the operation intent.
Concurrency, Copy, and Multipart Boundaries
- -Trace all writers for the same key, including multipart completion and copy operations.
- -Do not calculate multipart ETags locally for conditional writes; consume the ETag returned by S3.
Decision Shortcut: 412 vs 409 vs NoSuchKey
- -If a conditional header evaluated false on an existing target, stay on PreconditionFailed.
- -If the key disappeared before the operation, inspect NoSuchKey and version/delete-marker behavior.
- -If the request conflicts with broader workflow state without a conditional header mismatch, inspect conflict-style errors instead.
Wrong Fix to Avoid
- -Do not remove
If-MatchorIf-None-Matchjust to stop 412s if the guard prevents lost updates or accidental overwrites. - -Do not blind-retry the same stale conditional request without a fresh
HeadObject. - -Do not treat PreconditionFailed as S3 availability failure; S3 is enforcing the condition you sent.
Implementation Examples
2026-04-24T16:08:39Z bucket=config-prod key=manifests/current.json
ifMatch="7b8f0b2d6e5c" currentEtag="d41d8cd98f00b204e9800998ecf8427e"
status=412 error=PreconditionFailed requestId=4W1Q7PK0Z9CR4V8Maws s3api head-object \
--bucket config-prod \
--key manifests/current.json \
--query '{ETag:ETag,LastModified:LastModified,VersionId:VersionId,ContentLength:ContentLength}'async function guardedPut(bucket, key, body) {
const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
try {
await s3.send(new PutObjectCommand({
Bucket: bucket,
Key: key,
Body: body,
IfMatch: head.ETag,
}));
} catch (err) {
if (err.name === 'PreconditionFailed') {
// Re-read, merge, and retry with fresh validators.
}
}
}aws s3api put-object \
--bucket config-prod \
--key manifests/new.json \
--body manifest.json \
--if-none-match "*"
# Returns PreconditionFailed if the key already exists.Incident Timeline
16:04 UTC
A client reads object state and stores a validator
Signal: Worker, SDK, browser, or copy pipeline stores an ETag, Last-Modified value, version ID, or size for a later conditional operation.
Why it matters: The validator is only safe while the object remains unchanged.
16:07 UTC
Another writer changes the object first
Signal: ETag advances through PutObject, CopyObject, CompleteMultipartUpload, overwrite, or delete/recreate behavior.
Why it matters: The pending conditional request is now stale.
16:08 UTC
S3 rejects the operation with PreconditionFailed
Signal: If-Match, If-None-Match, or timestamp precondition evaluates false.
Why it matters: The object guard is working; the client needs fresh state, not an unguarded replay.
16:13 UTC
Client refreshes validators and retries intentionally
Signal: The writer re-reads object metadata, rebases the intended update, or handles create-if-absent as already-created.
Why it matters: That confirms the incident lived in stale conditional metadata or write ordering.
Seen in Production
Two workers update the same S3 manifest with stale ETags
Frequency: common
Example: Worker A commits a new manifest, then Worker B tries to overwrite using the old ETag and receives PreconditionFailed.
Fix: Re-read the manifest, merge changes, and retry with the current ETag or serialize writes by key.
Create-if-absent retry sees object already created
Frequency: medium
Example: A network retry repeats If-None-Match: * after the first attempt successfully created the object.
Fix: Treat PreconditionFailed as idempotent success only after verifying the existing object matches expected content.
Copy operation uses stale source ETag
Frequency: medium
Example: Artifact copy validates a source ETag, but the build process replaces the source before copy begins.
Fix: Copy from a versioned source object or refresh source validators before starting the copy.
Wrong Fix vs Better Fix
Remove precondition vs refresh validator
Wrong fix: Delete If-Match so the overwrite succeeds under contention.
Better fix: Read current object metadata, merge or rebase the intended change, and retry with fresh If-Match.
Why this is better: The precondition prevents lost updates and stale copy/range behavior.
Retry same request vs classify intent
Wrong fix: Replay the exact same conditional request with fixed backoff only.
Better fix: Classify whether the request is guarded overwrite, create-if-absent, cache validation, or copy/range safety before retrying.
Why this is better: Each intent has a different success condition and stale validators keep failing deterministically.
Blame S3 vs find the competing writer
Wrong fix: Treat PreconditionFailed spikes like a regional S3 health issue.
Better fix: Trace same-key writers, retries, multipart completions, copy jobs, and stale cache validators.
Why this is better: PreconditionFailed usually means S3 enforced state integrity exactly as requested.
Debugging Tools
- -aws s3api head-object
- -CloudTrail S3 data events
- -S3 server access logs
- -Application traces with request ID, ETag, version ID, and writer identity
How to Verify the Fix
- -Perform the conditional operation after a fresh
HeadObjectand confirm it succeeds only when validators are current. - -Run stale ETag and create-if-absent tests and confirm PreconditionFailed still protects correctness.
- -Verify hot-key writer coordination avoids infinite retry loops during contention.
- -Confirm PreconditionFailed rates drop in application logs, CloudTrail data events, and S3 request metrics.
How to Prevent Recurrence
- -Wrap conditional S3 writes in a shared read-refresh-rebase helper.
- -Use queue partitioning, object-versioned manifests, or an external coordination store for high-contention keys.
- -Keep ETag caches short-lived and invalidate them after any write, copy, multipart completion, or restore workflow.
- -Emit separate telemetry for guarded overwrite failures, create-if-absent conflicts, copy precondition failures, and range validator mismatches.
Pro Tip
- -use
If-None-Match: *for create-if-absent flows and treat the 412 as a safe duplicate-create signal rather than an outage.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.