{"record":{"id":"20a33d898fd5f9fc","repo":"chroma-core/chroma","slug":"please-install-the-xenova-transformers-package-to","errorCode":null,"errorMessage":"Please install the @xenova/transformers package to use the TransformersEmbeddingFunction, `npm install @xenova/transformers`","messagePattern":"Please install the @xenova/transformers package to use the TransformersEmbeddingFunction, `npm install @xenova/transformers`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts","lineNumber":85,"sourceCode":"        reject(e);\n      }\n    });\n\n    let pipe = await this.pipelinePromise;\n    let output = await pipe(texts, { pooling: \"mean\", normalize: true });\n    return output.tolist();\n  }\n\n  private async loadClient() {\n    if (this.transformersApi) return;\n    try {\n      // eslint-disable-next-line global-require,import/no-extraneous-dependencies\n      let { pipeline } = await TransformersEmbeddingFunction.import();\n      TransformersApi = pipeline;\n    } catch (_a) {\n      // @ts-ignore\n      if (_a.code === \"MODULE_NOT_FOUND\") {\n        throw new Error(\n          \"Please install the @xenova/transformers package to use the TransformersEmbeddingFunction, `npm install @xenova/transformers`\",\n        );\n      }\n      throw _a; // Re-throw other errors\n    }\n    this.transformersApi = TransformersApi;\n  }\n\n  /** @ignore */\n  static async import(): Promise<{\n    // @ts-ignore\n    pipeline: typeof import(\"@xenova/transformers\");\n  }> {\n    try {\n      // @ts-ignore\n      const { pipeline } = await import(\"@xenova/transformers\");\n      return { pipeline };\n    } catch (e) {","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nnew TransformersEmbeddingFunction({ model: \"Xenova/all-MiniLM-L6-v2\" });\nawait collection.add({ ids: [\"1\"], documents: [\"hi\"] }); // throws on first generate()\n\n// after\n// shell: npm install @xenova/transformers\nnew TransformersEmbeddingFunction({ model: \"Xenova/all-MiniLM-L6-v2\" });\nawait collection.add({ ids: [\"1\"], documents: [\"hi\"] });","handlingStrategy":"validation","validationCode":"// Fail at startup with a clear message instead of on first add()\ntry {\n  await import(\"@xenova/transformers\");\n} catch {\n  throw new Error(\"@xenova/transformers is required for local embeddings. Run: npm install @xenova/transformers\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["transformers","embeddings","optional-dependency","npm","local-inference"],"backgroundTag":"missing-npm-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}