chroma-core/chroma · error · Error

Please install @xenova/transformers as a dependency with, e.

Error message

Please install @xenova/transformers as a dependency with, e.g. `npm install @xenova/transformers`

What it means

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'.

Source

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

          "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) {
      throw new Error(
        "Please install @xenova/transformers as a dependency with, e.g. `npm install @xenova/transformers`",
      );
    }
  }

  buildFromConfig(config: StoredConfig): TransformersEmbeddingFunction {
    return new TransformersEmbeddingFunction({
      model: config.model,
      revision: config.revision,
      quantized: config.quantized,
    });
  }

  getConfig(): StoredConfig {
    return {
      model: this.model,
      revision: this.revision,
      quantized: this.quantized,

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

# before: Dockerfile
FROM node:20-alpine
RUN npm ci
# transformers import fails on musl -> misleading 'Please install' error

# after: Dockerfile
FROM node:20-bookworm-slim
RUN npm ci

Defensive patterns

Strategy: validation

Validate before calling

// Distinguish 'not installed' from 'installed but broken' at startup
try {
  const mod = await import("@xenova/transformers");
  if (typeof mod.pipeline !== "function") throw new Error("pipeline missing");
} catch (e) {
  const code = (e as NodeJS.ErrnoException)?.code;
  if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
    throw new Error("Install @xenova/transformers");
  }
  throw new Error(`@xenova/transformers installed but failed to load: ${e}`); // native/WASM/env issue
}

Prevention

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.

When it happens

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

Common situations: 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.

Related errors

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