rohitg00/agentmemory · error · Error

Install @huggingface/transformers for CLIP embeddings: npm i

Error message

Install @huggingface/transformers for CLIP embeddings: npm install @huggingface/transformers

What it means

The CLIP embedding provider lazily imports `@huggingface/transformers` at first use; if the dynamic import fails with ERR_MODULE_NOT_FOUND it rethrows this actionable message. The library treats the transformers package as an optional peer dependency, so CLIP embeddings are unavailable until you install it.

Source

Thrown at src/providers/embedding/clip.ts:64

    const t = await loadTransformers();
    this.textExtractor = (await t.pipeline("feature-extraction", this.modelId, { dtype: "q8" })) as ClipPipeline;
    return this.textExtractor;
  }

  private async getImageExtractor(): Promise<ClipPipeline> {
    if (this.imageExtractor) return this.imageExtractor;
    const t = await loadTransformers();
    this.imageExtractor = (await t.pipeline("image-feature-extraction", this.modelId, { dtype: "q8" })) as ClipPipeline;
    return this.imageExtractor;
  }
}

async function loadTransformers(): Promise<TransformersModule> {
  try {
    return await import("@huggingface/transformers");
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") {
      throw new Error(
        "Install @huggingface/transformers for CLIP embeddings: npm install @huggingface/transformers",
      );
    }
    throw err;
  }
}

async function loadImage(
  t: TransformersModule,
  src: string,
): Promise<RawImage> {
  if (src.startsWith("data:")) {
    const comma = src.indexOf(",");
    const b64 = comma >= 0 ? src.slice(comma + 1) : src;
    const buf = Buffer.from(b64, "base64");
    return t.RawImage.fromBlob(new Blob([buf]));
  }
  const data = await readFile(src);

View on GitHub (pinned to e04ba88819)

Solutions

1. Run `npm install @huggingface/transformers` (or the equivalent for your package manager) in the project root.
2. Restart the process after installing — dynamic import caches failures only per-call, but module resolution may need a fresh start.
3. If you don't need CLIP, switch to another embedding provider (OpenAI, Gemini, Cohere, local) so loadTransformers is never called.
4. If installed but still failing, check Node version compatibility and that the package resolves (`node -e "import('@huggingface/transformers')"`).

Example fix

// before
npm install  # @huggingface/transformers missing -> CLIP provider throws
// after
npm install @huggingface/transformers
npm run build && npm start

// Probe before selecting CLIP
async function clipAvailable(): Promise<boolean> {
  try { await import("@huggingface/transformers"); return true; }
  catch { return false; }
}
const provider = (await clipAvailable()) ? new ClipProvider() : new LocalEmbeddingProvider();

try {
  provider = new ClipProvider();
} catch (e) {
  if (e instanceof Error && e.message.includes("Install @huggingface/transformers")) {
    console.warn("CLIP unavailable; falling back to default text embeddings");
    provider = new DefaultEmbeddingProvider();
  } else throw e;
}

When it happens

Trigger: Selecting the CLIP embedding provider (multimodal image/text embeddings) when `@huggingface/transformers` is not present in node_modules — e.g. it was never installed, was in optionalDependencies and skipped, or the import throws ERR_MODULE_NOT_FOUND for another resolution reason.

Common situations: Fresh clone where only `npm install` of core deps ran; pnpm/yarn PnP strict installs that don't hoist optional peers; using a version of the package before/after the transformers dependency became optional; Node version too old for the package's export map causing resolution failure.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• [agentmemory] Refusing to start: persisted vector index has
• ${envName} must be a positive integer, got: ${override}
• COHERE_API_KEY is required
• Cohere embedding failed (${response.status}): ${err}
• GEMINI_API_KEY is required

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/e5d02dcf4fa4c3f1. Report an issue: GitHub.