chroma-core/chroma · error · ChromaValueError

Your API key is scoped to more than 1 DB. Please provide a D

Error message

Your API key is scoped to more than 1 DB. Please provide a DB name to the CloudClient constructor

What it means

Thrown by ChromaClient._path() (chroma-client.ts:201) as a ChromaValueError when the identity lookup returns either more than one unique database or the wildcard "*". Because _path() must auto-select a single database for every request, an ambiguous scope cannot be resolved automatically, so the library refuses to guess and asks you to name the database explicitly.

Source

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

  }

  public get headers(): Record<string, string> | undefined {
    return this._headers;
  }

  /** @ignore */
  public async _path(): Promise<{ tenant: string; database: string }> {
    if (!this._tenant || !this._database) {
      const { tenant, databases } = await this.getUserIdentity();
      const uniqueDBs = [...new Set(databases)];
      this._tenant = tenant;
      if (uniqueDBs.length === 0) {
        throw new ChromaUnauthorizedError(
          `Your API key does not have access to any DBs for tenant ${this.tenant}`,
        );
      }
      if (uniqueDBs.length > 1 || uniqueDBs[0] === "*") {
        throw new ChromaValueError(
          "Your API key is scoped to more than 1 DB. Please provide a DB name to the CloudClient constructor",
        );
      }
      this._database = uniqueDBs[0];
    }
    return { tenant: this._tenant, database: this._database };
  }

  /**
   * Gets the user identity information including tenant and accessible databases.
   * @returns Promise resolving to user identity data
   */
  public async getUserIdentity(): Promise<UserIdentity> {
    const { data } = await AuthenticationService.getUserIdentity({
      client: this.apiClient,
    });
    return data;
  }

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. Pass an explicit database to the constructor: new CloudClient({ apiKey, database: "my-db" }).
  2. Alternatively pass both tenant and database if you also want to skip the identity round-trip.
  3. Or issue a narrower API key scoped to exactly one database in the cloud console.
  4. Call client.getUserIdentity() first to see the exact list of DB names to choose from.

Example fix

// before
const client = new CloudClient({ apiKey: process.env.CHROMA_API_KEY });
await client.listCollections(); // ChromaValueError: scoped to more than 1 DB

// after
const client = new CloudClient({
  apiKey: process.env.CHROMA_API_KEY,
  database: "production",
});
await client.listCollections();
Defensive patterns

Strategy: validation

Validate before calling

const identity = await client.getUserIdentity();
const dbs = [...new Set(identity.databases)];
if (dbs.length > 1 || dbs[0] === "*") {
  if (!process.env.CHROMA_DATABASE) throw new Error("Set CHROMA_DATABASE: key sees " + dbs.join(", "));
}
const client = new CloudClient({ apiKey: KEY, database: process.env.CHROMA_DATABASE });

Try / catch

try {
  await client.listCollections();
} catch (e) {
  if (e instanceof ChromaValueError && e.message.includes("scoped to more than 1 DB")) {
    // re-construct CloudClient with an explicit database name
  }
  throw e;
}

Prevention

When it happens

Trigger: Constructing a CloudClient without a database argument where the API key grants access to multiple databases, or a wildcard ("*") key that spans all DBs in the tenant; then calling any method that goes through _path() (listCollections, createCollection, getCollection, ...).

Common situations: Using a broad admin/project-level Chroma Cloud API key instead of a per-database key; a new database was added to the tenant so a previously single-DB key now resolves to two; migrating from single-DB to multi-DB cloud projects.

Related errors

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