{"record":{"id":"d2f5b3248f50656e","repo":"chroma-core/chroma","slug":"please-install-the-openai-package-to-use-the-opena","errorCode":null,"errorMessage":"Please install the openai package to use the OpenAIEmbeddingFunction, e.g. `npm install openai`","messagePattern":"Please install the openai package to use the OpenAIEmbeddingFunction, e\\.g\\. `npm install openai`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts","lineNumber":134,"sourceCode":"    this.org_id = openai_organization_id ?? \"\";\n    this.model = openai_model;\n    this.dimensions = openai_embedding_dimensions ?? 1536;\n  }\n\n  private async loadClient() {\n    // cache the client\n    if (this.openaiApi) return;\n\n    try {\n      const { openai, version } = await OpenAIEmbeddingFunction.import();\n      OpenAIApi = openai;\n      let versionVar: string = version;\n      openAiVersion = versionVar.replace(/[^0-9.]/g, \"\");\n      openAiMajorVersion = parseInt(openAiVersion.split(\".\")[0]);\n    } catch (_a) {\n      // @ts-ignore\n      if (_a.code === \"MODULE_NOT_FOUND\") {\n        throw new Error(\n          \"Please install the openai package to use the OpenAIEmbeddingFunction, e.g. `npm install openai`\",\n        );\n      }\n      throw _a; // Re-throw other errors\n    }\n\n    if (openAiMajorVersion > 3) {\n      this.openaiApi = new OpenAIAPIv4(this.api_key);\n    } else {\n      this.openaiApi = new OpenAIAPIv3({\n        organization: this.org_id,\n        apiKey: this.api_key,\n      });\n    }\n  }\n\n  public async generate(texts: string[]): Promise<number[][]> {\n    await this.loadClient();","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts#L116-L152","documentation":"OpenAIEmbeddingFunction.loadClient() lazily imports the optional openai package (plus openai/version to detect v3 vs v4 API shapes and pick the right client constructor) on the first generate() call. If that import fails with MODULE_NOT_FOUND, this install-hint error is thrown; other failures are re-thrawn raw.","triggerScenarios":"Creating a collection with the OpenAI embedding function and triggering the first generate()/add() in a project where the openai npm package is not installed.","commonSituations":"Installing chromadb without the openai SDK; monorepo hoisting issues; bundler errors lacking .code (a raw error surfaces instead); slim Docker stages dropping the dependency.","solutions":["npm install openai in the executing app, then retry","If installed but failing, test the import directly: node -e \"import('openai').then(()=>console.log('ok'),e=>console.error(e))\"","Use an explicit embedding function whose dependency you already ship if openai is unwanted","Clean reinstall from the lockfile (npm ci) to repair a partially installed tree"],"exampleFix":"// before\nconst ef = new OpenAIEmbeddingFunction({ openai_api_key: KEY });\nawait ef.generate([\"ping\"]); // -> Please install the openai package...\n\n// after\n// $ npm install openai\nawait ef.generate([\"ping\"]); // ok","handlingStrategy":"validation","validationCode":"async function openAiPkgAvailable(): Promise<boolean> {\n  try {\n    await import(\"openai\");\n    return true;\n  } catch {\n    return false;\n  }\n}\n// before using the OpenAI embedding function:\nif (!(await openAiPkgAvailable())) throw new Error(\"Install the openai npm package to use OpenAI embeddings\");","typeGuard":null,"tryCatchPattern":"try {\n  await collection.add({ ids, documents });\n} catch (e) {\n  if (e instanceof Error && /install the openai package/.test(e.message)) {\n    // dependency missing: install openai or switch embedding function\n  }\n  throw e;\n}","preventionTips":["Declare the openai SDK as a direct dependency of the deploying app","Smoke-test the first generate() at startup","Use npm ci in CI so the optional dependency tree is reproducible"],"tags":["npm","openai","optional-dependency","module-not-found","lazy-import","embeddings"],"backgroundTag":"module-not-found","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}