{"record":{"id":"2673c45bda3dc4fe","repo":"chroma-core/chroma","slug":"please-install-the-chromadb-default-embed-package","errorCode":null,"errorMessage":"Please install the chromadb-default-embed package to use the DefaultEmbeddingFunction, `npm install chromadb-default-embed`","messagePattern":"Please install the chromadb-default-embed package to use the DefaultEmbeddingFunction, `npm install chromadb-default-embed`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts","lineNumber":115,"sourceCode":"        \"DefaultEmbeddingFunction model cannot be changed after initialization.\",\n      );\n    }\n  }\n\n  validateConfig(config: StoredConfig): void {\n    validateConfigSchema(config, \"transformers\");\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 DefaultEmbeddingFunction.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 chromadb-default-embed package to use the DefaultEmbeddingFunction, `npm install chromadb-default-embed`\",\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(\"chromadb-default-embed\");\n  }> {\n    try {\n      // @ts-ignore\n      const { pipeline } = await import(\"chromadb-default-embed\");\n      return { pipeline };\n    } catch (e) {","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/js/packages/chromadb-core/src/embeddings/DefaultEmbeddingFunction.ts#L97-L133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: relies on the optional default embedder\nconst ef = new DefaultEmbeddingFunction();\nawait collection.add({ ids, documents }); // first embed -> Error: Please install chromadb-default-embed...\n\n// after: install it once, or be explicit\n// $ npm install chromadb-default-embed\nconst ef = new DefaultEmbeddingFunction();\nawait ef.generate([\"ping\"]); // ok","handlingStrategy":"validation","validationCode":"let available: boolean | null = null;\nasync function defaultEmbedAvailable(): Promise<boolean> {\n  if (available === null) {\n    try {\n      await import(\"chromadb-default-embed\");\n      available = true;\n    } catch {\n      available = false;\n    }\n  }\n  return available;\n}\n// before createCollection:\nif (!(await defaultEmbedAvailable())) {\n  throw new Error(\"Install chromadb-default-embed or pass an explicit embedding function\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  await collection.add({ ids, documents });\n} catch (e) {\n  if (e instanceof Error && /chromadb-default-embed/.test(e.message)) {\n    // dependency missing: surface install instructions or switch to an explicit embedding function\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["npm","optional-dependency","embeddings","module-not-found","lazy-import"],"backgroundTag":"module-not-found","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}