rohitg00/agentmemory · error · Error

Install @huggingface/transformers for local embeddings: npm

Error message

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

What it means

LocalEmbeddingProvider relies on the optional peer dependency @huggingface/transformers to run on-device embedding models. The package is intentionally not bundled, so getExtractor() attempts a dynamic import and, when Node reports ERR_MODULE_NOT_FOUND, throws this actionable install message instead of an opaque module-not-found stack.

Source

Thrown at src/providers/embedding/local.ts:34

  }

  async embedBatch(texts: string[]): Promise<Float32Array[]> {
    const extractor = await this.getExtractor();
    const output = await extractor(texts, {
      pooling: "mean",
      normalize: true,
    });
    return output.tolist().map((v) => new Float32Array(v));
  }

  private async getExtractor() {
    if (this.extractor) return this.extractor;
    let transformers: typeof import("@huggingface/transformers");
    try {
      transformers = await import("@huggingface/transformers");
    } catch (err) {
      if ((err as NodeJS.ErrnoException).code === "ERR_MODULE_NOT_FOUND") {
        throw new Error(
          "Install @huggingface/transformers for local embeddings: npm install @huggingface/transformers",
        );
      }
      throw err;
    }
    this.extractor = (await transformers.pipeline(
      "feature-extraction",
      "Xenova/all-MiniLM-L6-v2",
      { dtype: "q8" },
    )) as FeatureExtractor;
    return this.extractor;
  }
}

View on GitHub (pinned to e04ba88819)

Solutions

1. Run: npm install @huggingface/transformers (or pnpm add / yarn add equivalent)
2. Pin a compatible version if the installed transformers API differs (pipeline export moved across majors)
3. If local inference is not actually wanted, configure a remote provider (openai/openrouter/voyage) instead

Example fix

// before
npm install
// after (add the optional local-embeddings dependency)
npm install @huggingface/transformers

let localEmbeddingsAvailable = false;
try {
  await import('@huggingface/transformers');
  localEmbeddingsAvailable = true;
} catch { localEmbeddingsAvailable = false; }
// before choosing provider type 'local', check localEmbeddingsAvailable

function canUseLocalEmbeddings(m: unknown): m is { pipeline: unknown } {
  return !!m && typeof (m as any).pipeline === 'function';
}

try {
  return await localProvider.embed(text);
} catch (err) {
  if (err instanceof Error && err.message.includes('Install @huggingface/transformers')) {
    console.error('Local embeddings need: npm install @huggingface/transformers');
    return fallbackProvider.embed(text);
  }
  throw err;
}

When it happens

Trigger: Selecting the 'local' embedding provider (LocalEmbeddingProvider) and calling embed()/embedBatch() for the first time (lazy extractor initialization) in a project where @huggingface/transformers is not installed.

Common situations: Fresh install of agentmemory without optional dependencies; CI image stripped of heavy ML deps; user switched AGENTMEMORY embedding provider to 'local' without adding the dependency; pnpm/yarn hoisting differences leaving the optional peer unresolved.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Install @huggingface/transformers for CLIP embeddings: npm i
• Embedding dimension mismatch in ${provider.name}.${where}: e
• OpenAI embedding failed (${response.status}): ${err}
• OpenRouter embedding failed (${response.status}): ${err}
• Voyage embedding failed (${response.status}): ${err}

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