PreconditionFailed

What Does Precondition Failed Mean?

PreconditionFailed is S3's way of saying: "The data has changed since you last looked at it." It prevents the "Lost Update" problem. When you send an If-Match header with an ETag, S3 ensures the object is exactly in the state you expect before performing the write. If another process modified the object in the millisecond between your read and write, S3 aborts your request to save you from corrupting the data.

Common Causes

• -Race Conditions: Two Lambda functions or users trying to update the same JSON config file at the exact same time.
• -Stale ETags: Using a cached ETag from a previous session that is no longer valid because the object was updated or replaced.
• -Incorrect Header Usage: Using If-Unmodified-Since with a timestamp that is slightly off due to clock skew or aggressive caching.
• -Creation Conflicts: Using If-None-Match: * to ensure a file is new, but the file already exists.

How to Fix Precondition Failed

1. 1Re-Fetch the ETag: Immediately call HeadObject to get the latest ETag and last-modified date.
2. 2Implement Retry-Loop: Catch the 412 error, pull the fresh data, merge your changes, and try the conditional write again.
3. 3Prefer ETags over Timestamps: Always use If-Match with ETags for higher precision than timestamp-based conditions.
4. 4Force Overwrite (If Safe): If you do not care about concurrent changes, simply remove the If-Match header to perform a "blind write."

Step-by-Step Diagnosis for Precondition Failed

1. 1Confirm which header failed (usually If-Match in the request logs).
2. 2Compare the ETag in your request with the one currently on the object using aws s3api head-object.
3. 3Check CloudTrail for concurrent PutObject calls to the same key from different IAM identities.
4. 4Verify if your application is caching ETags too aggressively (e.g., in a Redis or local memory store).

async function safeUpdate(bucket, key, newData) {
  const head = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
  
  try {
    await s3.send(new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      Body: newData,
      IfMatch: head.ETag // Only write if ETag hasn't changed
    }));
  } catch (err) {
    if (err.name === 'PreconditionFailed') {
      // Re-fetch and retry logic here
    }
  }
}

aws s3api put-object --bucket my-bucket --key new-file.txt \
    --body "hello" --if-none-match "*"
# Returns PreconditionFailed if new-file.txt already exists.

How to Verify the Fix

• -Successfully perform a conditional PutObject after a fresh HeadObject call.
• -Verify that the error only triggers when the ETag is intentionally changed.
• -Ensure your retry logic does not enter an infinite loop during high-contention periods.

How to Prevent Recurrence

• -Always Fetch Fresh: Call HeadObject immediately before any conditional write.
• -Use DynamoDB for Locks: For extremely high-contention objects, consider using DynamoDB's atomic counters or conditional expressions as a distributed lock manager.
• -Shorten Cache TTL: If you must cache ETags, keep the TTL extremely short (seconds, not minutes).
• -Pro-tip: Use If-None-Match: * when you want to ensure you are creating a NEW object. This returns PreconditionFailed if the key is already taken, preventing accidental overwrites of existing files.

Related Errors

Decision Support

Official References

• -S3 Conditional Requests Guide
• -Optimistic Locking in S3
• -RFC 9110 Section 13.1 - Conditional Requests
• -AWS Official Documentation