chroma-core/chroma · error · Error

Please install the @xenova/transformers package to use the T

Error message

Please install the @xenova/transformers package to use the TransformersEmbeddingFunction, `npm install @xenova/transformers`

What it means

TransformersEmbeddingFunction lazily imports @xenova/transformers on the first generate() call. The package is an intentionally optional peer dependency so bundles that never use local transformers stay small; when the dynamic import fails with code MODULE_NOT_FOUND this install hint is thrown instead of the raw import error.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts:85

        reject(e);
      }
    });

    let pipe = await this.pipelinePromise;
    let output = await pipe(texts, { pooling: "mean", normalize: true });
    return output.tolist();
  }

  private async loadClient() {
    if (this.transformersApi) return;
    try {
      // eslint-disable-next-line global-require,import/no-extraneous-dependencies
      let { pipeline } = await TransformersEmbeddingFunction.import();
      TransformersApi = pipeline;
    } catch (_a) {
      // @ts-ignore
      if (_a.code === "MODULE_NOT_FOUND") {
        throw new Error(
          "Please install the @xenova/transformers package to use the TransformersEmbeddingFunction, `npm install @xenova/transformers`",
        );
      }
      throw _a; // Re-throw other errors
    }
    this.transformersApi = TransformersApi;
  }

  /** @ignore */
  static async import(): Promise<{
    // @ts-ignore
    pipeline: typeof import("@xenova/transformers");
  }> {
    try {
      // @ts-ignore
      const { pipeline } = await import("@xenova/transformers");
      return { pipeline };
    } catch (e) {

View on GitHub (pinned to aecdd12c8a)

Solutions

npm install @xenova/transformers (or yarn/pnpm add).
Verify it resolves in the same runtime: node -e "import('@xenova/transformers').then(m => console.log(typeof m.pipeline))"
In monorepos, add it to the package that actually constructs the function, not just the workspace root.
Rebuild Docker/CI images after installing so node_modules is fresh.

Example fix

// before
new TransformersEmbeddingFunction({ model: "Xenova/all-MiniLM-L6-v2" });
await collection.add({ ids: ["1"], documents: ["hi"] }); // throws on first generate()

// after
// shell: npm install @xenova/transformers
new TransformersEmbeddingFunction({ model: "Xenova/all-MiniLM-L6-v2" });
await collection.add({ ids: ["1"], documents: ["hi"] });

Defensive patterns

Strategy: validation

Validate before calling

// Fail at startup with a clear message instead of on first add()
try {
  await import("@xenova/transformers");
} catch {
  throw new Error("@xenova/transformers is required for local embeddings. Run: npm install @xenova/transformers");
}

Prevention

Add @xenova/transformers to the same package.json that builds the embedding function.
Include a startup dependency check in Docker/CI so missing optional deps fail the build, not the first query.

When it happens

Trigger: Constructing new TransformersEmbeddingFunction({ model: 'Xenova/all-MiniLM-L6-v2' }) and then calling collection.add({ ids, documents }) / collection.query() — the first embedding call triggers loadClient(), which fails because @xenova/transformers is not resolvable from the project.

Common situations: Switching from the default embedding function to transformers without adding the dependency; monorepo dependency hoisting dropping the package; Docker images built from a pruned package.json; switching bundling mode so node_modules layout changes.

Related errors

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