{"record":{"id":"f55dc481cf638d1e","repo":"chroma-core/chroma","slug":"your-api-key-is-scoped-to-more-than-1-db-please-p","errorCode":null,"errorMessage":"Your API key is scoped to more than 1 DB. Please provide a DB name to the CloudClient constructor","messagePattern":"Your API key is scoped to more than 1 DB\\. Please provide a DB name to the CloudClient constructor","errorType":"validation","errorClass":"ChromaValueError","httpStatus":null,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-client.ts","lineNumber":201,"sourceCode":"  }\n\n  public get headers(): Record<string, string> | undefined {\n    return this._headers;\n  }\n\n  /** @ignore */\n  public async _path(): Promise<{ tenant: string; database: string }> {\n    if (!this._tenant || !this._database) {\n      const { tenant, databases } = await this.getUserIdentity();\n      const uniqueDBs = [...new Set(databases)];\n      this._tenant = tenant;\n      if (uniqueDBs.length === 0) {\n        throw new ChromaUnauthorizedError(\n          `Your API key does not have access to any DBs for tenant ${this.tenant}`,\n        );\n      }\n      if (uniqueDBs.length > 1 || uniqueDBs[0] === \"*\") {\n        throw new ChromaValueError(\n          \"Your API key is scoped to more than 1 DB. Please provide a DB name to the CloudClient constructor\",\n        );\n      }\n      this._database = uniqueDBs[0];\n    }\n    return { tenant: this._tenant, database: this._database };\n  }\n\n  /**\n   * Gets the user identity information including tenant and accessible databases.\n   * @returns Promise resolving to user identity data\n   */\n  public async getUserIdentity(): Promise<UserIdentity> {\n    const { data } = await AuthenticationService.getUserIdentity({\n      client: this.apiClient,\n    });\n    return data;\n  }","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-client.ts#L183-L219","documentation":"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.","triggerScenarios":"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, ...).","commonSituations":"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.","solutions":["Pass an explicit database to the constructor: new CloudClient({ apiKey, database: \"my-db\" }).","Alternatively pass both tenant and database if you also want to skip the identity round-trip.","Or issue a narrower API key scoped to exactly one database in the cloud console.","Call client.getUserIdentity() first to see the exact list of DB names to choose from."],"exampleFix":"// before\nconst client = new CloudClient({ apiKey: process.env.CHROMA_API_KEY });\nawait client.listCollections(); // ChromaValueError: scoped to more than 1 DB\n\n// after\nconst client = new CloudClient({\n  apiKey: process.env.CHROMA_API_KEY,\n  database: \"production\",\n});\nawait client.listCollections();","handlingStrategy":"validation","validationCode":"const identity = await client.getUserIdentity();\nconst dbs = [...new Set(identity.databases)];\nif (dbs.length > 1 || dbs[0] === \"*\") {\n  if (!process.env.CHROMA_DATABASE) throw new Error(\"Set CHROMA_DATABASE: key sees \" + dbs.join(\", \"));\n}\nconst client = new CloudClient({ apiKey: KEY, database: process.env.CHROMA_DATABASE });","typeGuard":null,"tryCatchPattern":"try {\n  await client.listCollections();\n} catch (e) {\n  if (e instanceof ChromaValueError && e.message.includes(\"scoped to more than 1 DB\")) {\n    // re-construct CloudClient with an explicit database name\n  }\n  throw e;\n}","preventionTips":["Always pass database (and tenant) explicitly to CloudClient in multi-DB projects.","Use per-database scoped keys in automation so ambiguity is impossible.","Log getUserIdentity() output during onboarding to catch scope drift early."],"tags":["cloud","configuration","api-key","database","validation"],"backgroundTag":"ambiguous-resource-scope","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}