chroma-core/chroma · error · ChromaUniqueError

The resource already exists

Error message

The resource already exists

What it means

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).

Source

Thrown at clients/new-js/packages/chromadb/src/chroma-fetch.ts:95

    case 403:
      throw new ChromaForbiddenError(
        `You do not have permission to access the requested resource.`,
      );
    case 404:
      throw new ChromaNotFoundError(
        `The requested resource could not be found`,
      );
    case 409:
      const conflictBody = await getErrorBody(response);
      if (
        conflictBody.error === "ConditionalWriteConflictError" ||
        conflictBody.message === "conditional write conflict"
      ) {
        throw new ChromaConditionalWriteConflictError(
          conflictBody.message || "conditional write conflict",
        );
      }
      throw new ChromaUniqueError(
        conflictBody.message || "The resource already exists",
      );
    case 412:
      const preconditionBody = await getErrorBody(response);
      if (preconditionBody.error === "StaleReadError") {
        throw new ChromaStaleReadError(
          preconditionBody.message || "stale read",
        );
      }
      throw new ChromaClientError(
        preconditionBody.message || "Precondition Failed",
      );
    case 422:
      try {
        const body = await response.json();
        if (
          body &&
          body.message &&

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use getOrCreateCollection() instead of createCollection() when the collection may already exist.
2. Catch ChromaUniqueError and fall back to getCollection() for the same name.
3. Delete the existing collection first if you truly want a fresh one.
4. Guard setup code with a listCollections() existence check.

Example fix

// before
await client.createCollection({ name: "docs", embeddingFunction }); // throws if exists

// after
await client.getOrCreateCollection({ name: "docs", embeddingFunction });

const exists = (await client.listCollections()).some(c => c.name === name);
if (!exists) await client.createCollection({ name, embeddingFunction });

try {
  await client.createCollection({ name, embeddingFunction });
} catch (e) {
  if (e instanceof ChromaUniqueError) {
    return client.getCollection({ name }); // already created concurrently
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: Idempotent-looking provisioning code that calls createCollection on every deploy; parallel workers each trying to create the shared collection; leftover collections from previous tests.

Related errors

• The requested resource could not be found
• conditional write conflict

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/b2ff7c558665d06a. Report an issue: GitHub.