{"record":{"id":"b2ff7c558665d06a","repo":"chroma-core/chroma","slug":"the-resource-already-exists-b2ff7c","errorCode":null,"errorMessage":"The resource already exists","messagePattern":"The resource already exists","errorType":"http","errorClass":"ChromaUniqueError","httpStatus":409,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":95,"sourceCode":"    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 {\n        const body = await response.json();\n        if (\n          body &&\n          body.message &&","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L77-L113","documentation":"Thrown by chromaFetch (chroma-fetch.ts:95) as a ChromaUniqueError when the server returns 409 without the conditional-write marker. The canonical case is a uniqueness violation: most commonly createCollection with a name that already exists in the tenant/database (collection names are unique).","triggerScenarios":"client.createCollection({ name }) when a collection with that name already exists; concurrent creators racing to register the same collection name; re-running setup scripts that assume a clean tenant.","commonSituations":"Idempotent-looking provisioning code that calls createCollection on every deploy; parallel workers each trying to create the shared collection; leftover collections from previous tests.","solutions":["Use getOrCreateCollection() instead of createCollection() when the collection may already exist.","Catch ChromaUniqueError and fall back to getCollection() for the same name.","Delete the existing collection first if you truly want a fresh one.","Guard setup code with a listCollections() existence check."],"exampleFix":"// before\nawait client.createCollection({ name: \"docs\", embeddingFunction }); // throws if exists\n\n// after\nawait client.getOrCreateCollection({ name: \"docs\", embeddingFunction });","handlingStrategy":"fallback","validationCode":"const exists = (await client.listCollections()).some(c => c.name === name);\nif (!exists) await client.createCollection({ name, embeddingFunction });","typeGuard":null,"tryCatchPattern":"try {\n  await client.createCollection({ name, embeddingFunction });\n} catch (e) {\n  if (e instanceof ChromaUniqueError) {\n    return client.getCollection({ name }); // already created concurrently\n  }\n  throw e;\n}","preventionTips":["Use getOrCreateCollection() instead of createCollection() in idempotent setup code.","Make provisioning scripts re-runnable by handling ChromaUniqueError.","In races across workers, treat 409-on-create as success via getCollection fallback."],"tags":["http-409","duplicate","collection","uniqueness"],"backgroundTag":"duplicate-resource-conflict","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}