ConditionNotMet
Azure ConditionNotMet means one or more conditional headers evaluated false; reads can return 304 and writes typically return HTTP 412.
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 Condition Not Met Mean?
Azure evaluated the request against current storage state and the condition did not hold. The guard may be an ETag, timestamp, lease ID, append position, sequence number, source condition, or target condition; the fix is to refresh state and retry intentionally, not remove the guard blindly.
Common Causes
- -
If-Match,If-None-Match,If-Modified-Since, orIf-Unmodified-Sinceuses stale values after another writer updated the blob. - -Lease-dependent operations send an expired, missing, or mismatched lease ID.
- -Copy operations fail because source or target conditional headers no longer match current blob state.
- -Append or page blob requests violate append-position, max-size, or sequence-number conditions.
- -Parallel workers mutate the same blob, manifest, or checkpoint without ordered write coordination.
How to Fix Condition Not Met
- 1Read latest blob properties and refresh ETag, last-modified, lease, sequence, append-position, and copy metadata before retrying.
- 2Send conditional headers that match the operation intent: guarded overwrite, create-if-absent, cache validation, copy-if-current, or lease-protected write.
- 3Rebase the intended mutation on the current blob state instead of replaying the stale request.
- 4Serialize or partition hot-blob writers where repeated ConditionNotMet is caused by real contention.
- 5Keep the condition when it protects correctness; only remove it if a blind overwrite is explicitly acceptable.
Step-by-Step Diagnosis for Condition Not Met
- 1Capture
If-*, lease, source condition, target condition, append-position, and sequence-number headers with response status andx-ms-request-id. - 2Compare provided validators with current blob properties from a fresh properties request.
- 3Trace concurrent writers, copy jobs, lease lifecycle events, and append/page updates touching the same blob in the same window.
- 4Determine whether this is a read cache validation result, a write precondition failure, or a lease/append/page-specific condition.
- 5Retest with a read-refresh-rebase-write cycle and confirm stale validators still fail safely.
Seen in Production
- -Two queue workers update the same manifest blob; the second worker sends a stale
If-Matchand receives ConditionNotMet. - -A copy job uses a stale source ETag condition after the source blob was overwritten by a newer build artifact.
- -A lease-protected writer retries after its lease expired and the storage service rejects the stale lease condition.
- -An append blob writer assumes the previous append position is still current while another writer already appended bytes.
Conditional Header and ETag Integrity
- -Audit ETag refresh boundaries in client code and caches.
- -Inspect conditional header semantics per operation:
If-Matchfor guarded overwrite,If-None-Matchfor create/cache paths, source conditions for copy, and timestamp validators for freshness checks.
Lease and Writer Concurrency Controls
- -Validate lease lifecycle around mutating operations and reacquire when lease state changes.
- -Trace concurrent mutation paths and enforce single-writer guards for hot manifests, checkpoints, and append blobs.
Decision Shortcut: 304 Read vs 412 Write
- -If the failed request was a read/cache validation, ConditionNotMet may surface as 304 Not Modified and should not be treated as a failed write.
- -If the failed request was a mutation, stay on 412-style precondition handling and refresh validators.
- -If no conditional header was intended, inspect client middleware or SDK options that injected stale validators.
Wrong Fix to Avoid
- -Do not remove
If-Match, lease, append-position, or sequence guards just to make writes pass under contention. - -Do not retry the same stale conditional request without re-reading current blob properties.
- -Do not collapse ConditionNotMet into generic storage outage handling; the failed condition identifies the state guard.
Implementation Examples
2026-04-24T13:10:22Z container=manifests blob=feeds/current.json
ifMatch="0x8DC6A11B2F13C90" currentEtag="0x8DC6A11C8349A01"
status=412 error=ConditionNotMet xMsRequestId=1d79b8f2-c01e-0054-34aa-141ba8000000az storage blob show \
--account-name mediaeast \
--container-name manifests \
--name feeds/current.json \
--query '{etag:properties.etag,lastModified:properties.lastModified,leaseState:properties.lease.state}'const props = await blobClient.getProperties();
try {
await blobClient.uploadData(body, {
conditions: { ifMatch: props.etag },
overwrite: true,
});
} catch (error) {
if (error.details?.errorCode === 'ConditionNotMet') {
// Re-read, merge, and retry with fresh conditions.
}
}Incident Timeline
13:06 UTC
A client reads blob state and stores a validator
Signal: Worker, SDK, cache, or copy pipeline stores an ETag, timestamp, lease ID, append position, sequence number, or source condition.
Why it matters: That validator is only safe while the blob remains in the same state.
13:09 UTC
Another writer or lifecycle event changes the blob state
Signal: ETag advances, lease expires, append position moves, or source/target copy metadata changes.
Why it matters: The pending conditional request is now stale.
13:10 UTC
Azure rejects the request with ConditionNotMet
Signal: The response carries 304 for read validation or 412 for write precondition failure.
Why it matters: The storage guard is working; the client needs fresh state or a controlled rebase.
13:14 UTC
Client refreshes state and retries intentionally
Signal: The request is rebuilt with current validators, a renewed lease, or an updated append/sequence condition.
Why it matters: That confirms the incident lived in stale conditional metadata, not platform availability.
Seen in Production
Two workers update the same blob manifest with stale cached ETags
Frequency: common
Example: Second worker write returns 412 because first worker already committed a new version.
Fix: Refresh ETag before each write and serialize updates via queue partitioning.
Lease-based write path retries after lease expiry
Frequency: rare
Example: Client retries mutation with expired lease ID and receives ConditionNotMet.
Fix: Reacquire lease and regenerate conditional headers before retry.
Copy job uses a stale source condition
Frequency: medium
Example: Source artifact is overwritten between validation and copy, so the source ETag condition no longer matches.
Fix: Refresh source properties and rebuild copy conditions or restart from a stable artifact version.
Wrong Fix vs Better Fix
Remove condition vs refresh and rebase
Wrong fix: Drop If-Match, lease, append-position, or sequence conditions so the write succeeds.
Better fix: Read current properties, merge or rebase the intended mutation, then retry with fresh conditions.
Why this is better: The condition prevents lost updates, stale copies, and corrupted append/page writes.
Blind retry vs classify the failed condition
Wrong fix: Replay the same request with fixed backoff only.
Better fix: Identify whether ETag, lease, source condition, target condition, append position, or sequence number failed.
Why this is better: Each condition has a different recovery path and stale values keep failing deterministically.
Treat as outage vs find the competing writer
Wrong fix: Page storage availability responders for a ConditionNotMet spike.
Better fix: Trace concurrent writers, copy jobs, lease expiry, and cache validators for the affected blob key.
Why this is better: ConditionNotMet usually means the service enforced state integrity exactly as requested.
Debugging Tools
- -Blob properties/ETag inspection
- -Request capture of If-* and lease headers
- -Storage diagnostics with x-ms-request-id
- -Concurrency trace across worker jobs
How to Verify the Fix
- -Replay the mutation path with fresh validators and confirm conditional writes succeed only when state is current.
- -Run stale-validator tests and confirm outdated ETags, leases, append positions, and sequence numbers still fail safely.
- -Verify concurrency controls preserve intended write ordering under load.
- -Observe reduced ConditionNotMet rates in storage diagnostics and application traces after deployment.
How to Prevent Recurrence
- -Implement standard read-refresh-write helpers for all conditional storage operations.
- -Use bounded retries that always re-fetch blob properties before each attempt.
- -Partition, queue, or lock high-contention blobs to reduce cross-worker write races.
- -Emit separate metrics for read validation 304s, write precondition 412s, lease failures, and append/page condition failures.
Pro Tip
- -persist last-seen validator metadata with worker jobs and reject stale jobs before they reach the storage write call.
Decision Support
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.