chroma-core/chroma · error · Error

Please install the chromadb-default-embed package to use the

Error message

Please install the chromadb-default-embed package to use the DefaultEmbeddingFunction, `npm install chromadb-default-embed`

What it means

Thrown by DefaultEmbeddingFunction the first time it needs to embed text: loadClient() lazily dynamic-imports the optional chromadb-default-embed package (a transformers.js wrapper) and the import fails with MODULE_NOT_FOUND. The package is deliberately optional so the core chromadb client stays lightweight; this guard converts the raw module-resolution failure into an actionable install hint. Any other import error is re-thrown untouched.

Source

Thrown at clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts:115

        "DefaultEmbeddingFunction model cannot be changed after initialization.",
      );
    }
  }

  validateConfig(config: StoredConfig): void {
    validateConfigSchema(config, "transformers");
  }

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

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

View on GitHub (pinned to aecdd12c8a)

Solutions

Run npm install chromadb-default-embed (or the yarn/pnpm equivalent) in the app that executes the client, then retry
Or avoid the default embedder entirely: pass an explicit embedding function (e.g. new OpenAIEmbeddingFunction(...)) to createCollection
If the package is installed but the error persists, reproduce the import directly: node -e "import('chromadb-default-embed').then(()=>console.log('ok'),e=>console.error(e))" and fix the real error it prints (reinstall, npm ci, bundler config)
Confirm it landed in the right workspace: npm ls chromadb-default-embed

Example fix

// before: relies on the optional default embedder
const ef = new DefaultEmbeddingFunction();
await collection.add({ ids, documents }); // first embed -> Error: Please install chromadb-default-embed...

// after: install it once, or be explicit
// $ npm install chromadb-default-embed
const ef = new DefaultEmbeddingFunction();
await ef.generate(["ping"]); // ok

Defensive patterns

Strategy: validation

Validate before calling

let available: boolean | null = null;
async function defaultEmbedAvailable(): Promise<boolean> {
  if (available === null) {
    try {
      await import("chromadb-default-embed");
      available = true;
    } catch {
      available = false;
    }
  }
  return available;
}
// before createCollection:
if (!(await defaultEmbedAvailable())) {
  throw new Error("Install chromadb-default-embed or pass an explicit embedding function");
}

Try / catch

try {
  await collection.add({ ids, documents });
} catch (e) {
  if (e instanceof Error && /chromadb-default-embed/.test(e.message)) {
    // dependency missing: surface install instructions or switch to an explicit embedding function
  }
  throw e;
}

Prevention

Smoke-test every embedding function at startup: await ef.generate(["ping"]) before serving traffic
Add the optional embed package to package.json at scaffold time if you rely on the default embedder
Always pass an explicit embedding function to createCollection in production code

When it happens

Trigger: Constructing DefaultEmbeddingFunction (or creating/adding to a collection with no explicit embedding function, which falls back to the default) and triggering the first generate() call in a project where chromadb-default-embed is not resolvable in node_modules.

Common situations: Fresh npm install chromadb without the separate embed package; pnpm/strict monorepo hoisting dropping optional deps; slim Docker stages stripping optionalDependencies; edge/bundler runtimes where the thrown error lacks a .code so a different (raw) error surfaces instead.

Related errors

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