chroma-core/chroma · error · ChromaValueError

tenant and database must be set on the client before calling

Error message

tenant and database must be set on the client before calling collection(). Provide them in the ChromaClient constructor or use getCollection() instead.

What it means

Thrown synchronously by ChromaClient.collection(id) (chroma-client.ts:585) when either this._tenant or this._database is unset. The lightweight CollectionHandle needs tenant/database to route requests, and unlike getCollection() (which resolves them via the async _path() identity lookup), collection() is deliberately synchronous, so it requires them to already be present on the client.

Source

Thrown at clients/new-js/packages/chromadb/src/chroma-client.ts:585

      embeddingFunction: resolvedEmbeddingFunction,
      id: data.id,
      schema: serverSchema,
    });
  }

  /**
   * Returns a lightweight collection handle for the given collection ID.
   * The handle supports operations that don't require an embedding function
   * or schema (e.g., add with pre-computed embeddings, get, delete, count, search).
   * Operations that require an embedding function will throw a clear error
   * directing you to use {@link getCollection} instead.
   * @param id - The collection ID
   * @returns A Collection handle for the given ID
   * @throws ChromaValueError if tenant or database are not set on the client
   */
  public collection(id: string): Collection {
    if (!this._tenant || !this._database) {
      throw new ChromaValueError(
        "tenant and database must be set on the client before calling collection(). " +
          "Provide them in the ChromaClient constructor or use getCollection() instead.",
      );
    }

    return new CollectionHandle({
      chromaClient: this,
      apiClient: this.apiClient,
      id,
      tenant: this._tenant,
      database: this._database,
    });
  }

  /**
   * Deletes a collection and all its data.
   * @param options - Deletion options
   * @param options.name - The name of the collection to delete

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Provide tenant and database in the constructor: new ChromaClient({ tenant, database }) / new CloudClient({ apiKey, tenant, database }).
  2. Or use await client.getCollection(name) instead, which resolves tenant/database lazily.
  3. If you already know the values at call time, call any awaited method once (e.g. listCollections) to populate _tenant/_database, then use collection(id).

Example fix

// before
const client = new CloudClient({ apiKey: KEY }); // no tenant/database
const col = client.collection("col-id"); // throws ChromaValueError

// after
const client = new CloudClient({ apiKey: KEY, tenant: "my-tenant", database: "my-db" });
const col = client.collection("col-id"); // synchronous lightweight handle
Defensive patterns

Strategy: validation

Validate before calling

const identity = await client.getUserIdentity();
const ready = Boolean(identity.tenant && [...new Set(identity.databases)].length === 1);
if (!ready) {
  // fall back to the async API instead of the sync handle
  const col = await client.getCollection({ name: "docs" });
}

Type guard

const canUseSyncHandle = (c: ChromaClient): boolean =>
  // tenant/database must already be materialized on the client
  (c as any)._tenant != null && (c as any)._database != null; // prefer: construct with both instead

Try / catch

try {
  const col = client.collection(id);
} catch (e) {
  if (e instanceof ChromaValueError && e.message.includes("tenant and database must be set")) {
    return await client.getCollection({ name }); // async path resolves them
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling client.collection("<uuid>") on a client constructed without explicit tenant and database values — typically a CloudClient that relied on auto-discovery, or a ChromaClient whose tenant/database were never provided and whose _path() has not run yet.

Common situations: Switching code from await client.getCollection(name) to the fast sync handle API without adding tenant/database to the constructor; using an ID from another tenant; refactoring away from the async path.

Related errors

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