{"record":{"id":"394edf3f528d0d0b","repo":"chroma-core/chroma","slug":"conditional-write-conflict","errorCode":null,"errorMessage":"conditional write conflict","messagePattern":"conditional write conflict","errorType":"http","errorClass":"ChromaConditionalWriteConflictError","httpStatus":409,"severity":"warning","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":91,"sourceCode":"        } with status: ${status}`,\n      );\n    case 401:\n      throw new ChromaUnauthorizedError(`Unauthorized`);\n    case 403:\n      throw new ChromaForbiddenError(\n        `You do not have permission to access the requested resource.`,\n      );\n    case 404:\n      throw new ChromaNotFoundError(\n        `The requested resource could not be found`,\n      );\n    case 409:\n      const conflictBody = await getErrorBody(response);\n      if (\n        conflictBody.error === \"ConditionalWriteConflictError\" ||\n        conflictBody.message === \"conditional write conflict\"\n      ) {\n        throw new ChromaConditionalWriteConflictError(\n          conflictBody.message || \"conditional write conflict\",\n        );\n      }\n      throw new ChromaUniqueError(\n        conflictBody.message || \"The resource already exists\",\n      );\n    case 412:\n      const preconditionBody = await getErrorBody(response);\n      if (preconditionBody.error === \"StaleReadError\") {\n        throw new ChromaStaleReadError(\n          preconditionBody.message || \"stale read\",\n        );\n      }\n      throw new ChromaClientError(\n        preconditionBody.message || \"Precondition Failed\",\n      );\n    case 422:\n      try {","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L73-L109","documentation":"Thrown by chromaFetch (chroma-fetch.ts:91) as a ChromaConditionalWriteConflictError when the server returns 409 and the body identifies a ConditionalWriteConflictError. This is Chroma's optimistic-concurrency control: a write (add/upsert/update/delete) whose version precondition did not match the collection's current version lost the race against a concurrent writer, and the server rejected it so you can retry against the new state.","triggerScenarios":"Two concurrent writers mutating the same collection with version precondition headers (e.g. upsert with if-collection-version); long-running read-then-write sequences where the collection changed in between; high-concurrency ingestion pipelines using conditional writes.","commonSituations":"Parallel batch writers to one collection; retries after timeouts that actually succeeded server-side; cache of collection version kept too long before a conditional update.","solutions":["Catch ChromaConditionalWriteConflictError and retry the operation after re-reading the current collection version, ideally with jittered backoff.","Reduce write contention by funnelting writes through a single writer/queue for the hot collection.","Re-fetch the collection handle (to refresh its version) before each conditional write in long sessions.","If you do not need OCC guarantees, drop the version precondition parameter."],"exampleFix":"// before\nawait collection.upsert({ ids, documents, /* version: staleVersion */ }); // 409 conditional write conflict\n\n// after\ntry {\n  await collection.upsert({ ids, documents });\n} catch (e) {\n  if (e instanceof ChromaConditionalWriteConflictError) {\n    await sleep(50 * (1 + Math.random()));\n    return collection.upsert({ ids, documents }); // retry against fresh state\n  }\n  throw e;\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for (let attempt = 0; ; attempt++) {\n  try {\n    return await collection.upsert(payload);\n  } catch (e) {\n    if (e instanceof ChromaConditionalWriteConflictError && attempt < 5) {\n      await new Promise(r => setTimeout(r, 2 ** attempt * 50 + Math.random() * 100));\n      continue; // optionally refresh collection version here\n    }\n    throw e;\n  }\n}","preventionTips":["Re-fetch the collection version right before conditional writes in concurrent pipelines.","Serialize writers per collection (queue) when contention is high.","Treat this error as retryable by design — never surface it as a hard failure without one retry."],"tags":["http-409","concurrency","optimistic-concurrency","retryable"],"backgroundTag":"optimistic-lock-conflict","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}