chroma-core/chroma · error · Error

Please install the openai package to use the OpenAIEmbedding

Error message

Please install the openai package to use the OpenAIEmbeddingFunction, e.g. `npm install openai`

What it means

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.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/OpenAIEmbeddingFunction.ts:134

    this.org_id = openai_organization_id ?? "";
    this.model = openai_model;
    this.dimensions = openai_embedding_dimensions ?? 1536;
  }

  private async loadClient() {
    // cache the client
    if (this.openaiApi) return;

    try {
      const { openai, version } = await OpenAIEmbeddingFunction.import();
      OpenAIApi = openai;
      let versionVar: string = version;
      openAiVersion = versionVar.replace(/[^0-9.]/g, "");
      openAiMajorVersion = parseInt(openAiVersion.split(".")[0]);
    } catch (_a) {
      // @ts-ignore
      if (_a.code === "MODULE_NOT_FOUND") {
        throw new Error(
          "Please install the openai package to use the OpenAIEmbeddingFunction, e.g. `npm install openai`",
        );
      }
      throw _a; // Re-throw other errors
    }

    if (openAiMajorVersion > 3) {
      this.openaiApi = new OpenAIAPIv4(this.api_key);
    } else {
      this.openaiApi = new OpenAIAPIv3({
        organization: this.org_id,
        apiKey: this.api_key,
      });
    }
  }

  public async generate(texts: string[]): Promise<number[][]> {
    await this.loadClient();

View on GitHub (pinned to aecdd12c8a)

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

Example fix

// before
const ef = new OpenAIEmbeddingFunction({ openai_api_key: KEY });
await ef.generate(["ping"]); // -> Please install the openai package...

// after
// $ npm install openai
await ef.generate(["ping"]); // ok

Defensive patterns

Strategy: validation

Validate before calling

async function openAiPkgAvailable(): Promise<boolean> {
  try {
    await import("openai");
    return true;
  } catch {
    return false;
  }
}
// before using the OpenAI embedding function:
if (!(await openAiPkgAvailable())) throw new Error("Install the openai npm package to use OpenAI embeddings");

Try / catch

try {
  await collection.add({ ids, documents });
} catch (e) {
  if (e instanceof Error && /install the openai package/.test(e.message)) {
    // dependency missing: install openai or switch embedding function
  }
  throw e;
}

Prevention

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

When it happens

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

Common situations: Installing chromadb without the openai SDK; monorepo hoisting issues; bundler errors lacking .code (a raw error surfaces instead); slim Docker stages dropping the dependency.

Related errors

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