{
  "id": "data/mongodb-write-conflict-retry",
  "signature": "WriteConflict: write conflict due to concurrent update on the same document",
  "signature_zh": "WriteConflict：由于对同一文档的并发更新导致写入冲突",
  "regex": "WriteConflict.*write conflict|WriteConflict error|write conflict.*same document",
  "domain": "data",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "MongoDB's WiredTiger storage engine detects a write-write conflict when two operations try to modify the same document concurrently, and one of them must retry.",
  "root_cause_type": "generic",
  "root_cause_zh": "MongoDB 的 WiredTiger 存储引擎检测到写入-写入冲突，当两个操作试图同时修改同一文档时，其中一个必须重试。",
  "versions": [
    {
      "version": "MongoDB 4.4",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MongoDB 5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MongoDB 6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "MongoDB 7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "Unacknowledged writes can silently lose data and still cause conflicts at the storage engine level.",
      "fail_rate": 0.75,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The operation is atomic but still subject to WiredTiger's conflict detection; a retry is necessary.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "The conflict is not a timeout issue; it's a concurrent modification that must be retried or avoided.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Implement retry logic in the application with exponential backoff. Example in Node.js: `async function updateWithRetry(collection, filter, update, retries=3) { for (let i = 0; i < retries; i++) { try { return await collection.updateOne(filter, update); } catch (e) { if (e.code !== 112) throw e; await new Promise(r => setTimeout(r, 100 * Math.pow(2, i))); } } throw new Error('Max retries exceeded'); }`",
      "success_rate": 0.85,
      "how": "Implement retry logic in the application with exponential backoff. Example in Node.js: `async function updateWithRetry(collection, filter, update, retries=3) { for (let i = 0; i < retries; i++) { try { return await collection.updateOne(filter, update); } catch (e) { if (e.code !== 112) throw e; await new Promise(r => setTimeout(r, 100 * Math.pow(2, i))); } } throw new Error('Max retries exceeded'); }`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Use optimistic concurrency control with a version field: add a `__v` field to the document and increment it on each update; the update condition includes the current version.",
      "success_rate": 0.8,
      "how": "Use optimistic concurrency control with a version field: add a `__v` field to the document and increment it on each update; the update condition includes the current version.",
      "condition": "",
      "sources": []
    },
    {
      "action": "Reduce the likelihood of conflicts by sharding the collection on a field that distributes writes evenly across documents.",
      "success_rate": 0.7,
      "how": "Reduce the likelihood of conflicts by sharding the collection on a field that distributes writes evenly across documents.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Implement retry logic in the application with exponential backoff. Example in Node.js: `async function updateWithRetry(collection, filter, update, retries=3) { for (let i = 0; i < retries; i++) { try { return await collection.updateOne(filter, update); } catch (e) { if (e.code !== 112) throw e; await new Promise(r => setTimeout(r, 100 * Math.pow(2, i))); } } throw new Error('Max retries exceeded'); }`",
    "Use optimistic concurrency control with a version field: add a `__v` field to the document and increment it on each update; the update condition includes the current version.",
    "Reduce the likelihood of conflicts by sharding the collection on a field that distributes writes evenly across documents."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://www.mongodb.com/docs/manual/core/transactions-production-consideration/",
  "official_doc_section": null,
  "error_code": "WriteConflict",
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.78,
  "resolvable": "true",
  "first_seen": "2023-09-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}