{"record":{"id":"948682d5020419d7","repo":"chroma-core/chroma","slug":"please-install-xenova-transformers-as-a-dependenc","errorCode":null,"errorMessage":"Please install @xenova/transformers as a dependency with, e.g. `npm install @xenova/transformers`","messagePattern":"Please install @xenova/transformers as a dependency with, e\\.g\\. `npm install @xenova/transformers`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts","lineNumber":104,"sourceCode":"          \"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) {\n      throw new Error(\n        \"Please install @xenova/transformers as a dependency with, e.g. `npm install @xenova/transformers`\",\n      );\n    }\n  }\n\n  buildFromConfig(config: StoredConfig): TransformersEmbeddingFunction {\n    return new TransformersEmbeddingFunction({\n      model: config.model,\n      revision: config.revision,\n      quantized: config.quantized,\n    });\n  }\n\n  getConfig(): StoredConfig {\n    return {\n      model: this.model,\n      revision: this.revision,\n      quantized: this.quantized,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/TransformersEmbeddingFunction.ts#L86-L122","documentation":"Sibling of the MODULE_NOT_FOUND hint, thrown from TransformersEmbeddingFunction.import(): the catch discards the original error entirely, so ANY dynamic-import failure produces this message — including cases where @xenova/transformers IS installed but fails to load (corrupt install, onnxruntime-node native binding mismatch, bundler choking on .wasm assets). Treat it as 'import failed', not necessarily 'not installed'.","triggerScenarios":"First generate() where the package is installed but broken: onnxruntime-node cannot load in Alpine/musl images or missing glibc; webpack/rollup resolving the ESM package without its WASM files; partial node_modules after an interrupted install; Node version too old for the package's syntax/engines.","commonSituations":"Docker Alpine deployments of apps using transformers embeddings; bundler configs (webpack module.rules, serverless packs) that strip node_modules or .wasm assets; upgrading Node/onnxruntime versions.","solutions":["Test the import standalone in the same environment: node -e \"import('@xenova/transformers').then(() => console.log('ok')).catch(console.error)\" — the real error appears here.","If it is a native/WASM failure (onnxruntime, Invalid ELF header, Missing wasm), fix the environment: use a Debian-based (glibc) image, align onnxruntime-node with the platform, configure the bundler to copy .wasm files.","rm -rf node_modules package-lock.json && npm install to rule out a corrupt install.","Only if the standalone import says ERR_MODULE_NOT_FOUND is the package actually missing — then npm install @xenova/transformers."],"exampleFix":"# before: Dockerfile\nFROM node:20-alpine\nRUN npm ci\n# transformers import fails on musl -> misleading 'Please install' error\n\n# after: Dockerfile\nFROM node:20-bookworm-slim\nRUN npm ci","handlingStrategy":"validation","validationCode":"// Distinguish 'not installed' from 'installed but broken' at startup\ntry {\n  const mod = await import(\"@xenova/transformers\");\n  if (typeof mod.pipeline !== \"function\") throw new Error(\"pipeline missing\");\n} catch (e) {\n  const code = (e as NodeJS.ErrnoException)?.code;\n  if (code === \"ERR_MODULE_NOT_FOUND\" || code === \"MODULE_NOT_FOUND\") {\n    throw new Error(\"Install @xenova/transformers\");\n  }\n  throw new Error(`@xenova/transformers installed but failed to load: ${e}`); // native/WASM/env issue\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Test the transformers import in the exact deployment image (glibc vs musl) before shipping.","Keep .wasm assets and onnxruntime binaries out of bundler exclusion lists.","Because this error masks its cause, always reproduce the import standalone with node -e before debugging Chroma."],"tags":["transformers","embeddings","npm","wasm","native-module","docker"],"backgroundTag":"npm-package-load-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}