mem0ai/mem0 · error · Error

HuggingFace embedder requires an inference endpoint. Set `hu

Error message

HuggingFace embedder requires an inference endpoint. Set `huggingfaceBaseUrl` (or `baseURL`) in the embedder config, or the HUGGINGFACE_BASE_URL environment variable (e.g. a TEI server at http://localhost:8080/v1).

What it means

Thrown by the HuggingFaceEmbedder constructor when no inference endpoint can be resolved. Unlike other providers, this embedder does not call the HF Hub API — it speaks the OpenAI-compatible protocol to a self-hosted Text-Embeddings-Inference (TEI) server, so a base URL is mandatory. Resolution order: config.huggingfaceBaseUrl, config.baseURL, config.url, then process.env.HUGGINGFACE_BASE_URL. All four unset -> this error.

Source

Thrown at mem0-ts/src/oss/src/embeddings/huggingface.ts:30

 * `openai` client pointed at that base URL. No new dependency is required.
 *
 * A base URL is required. The Python provider's alternative local
 * `sentence-transformers` path has no lightweight TypeScript equivalent, so
 * hosted inference is the supported TS mode.
 */
export class HuggingFaceEmbedder implements Embedder {
  private openai: OpenAI;
  private model: string;

  constructor(config: EmbeddingConfig) {
    const baseURL =
      config.huggingfaceBaseUrl ||
      config.baseURL ||
      config.url ||
      process.env.HUGGINGFACE_BASE_URL;

    if (!baseURL) {
      throw new Error(
        "HuggingFace embedder requires an inference endpoint. Set " +
          "`huggingfaceBaseUrl` (or `baseURL`) in the embedder config, or the " +
          "HUGGINGFACE_BASE_URL environment variable (e.g. a TEI server at " +
          "http://localhost:8080/v1).",
      );
    }

    this.openai = new OpenAI({
      apiKey: config.apiKey || process.env.HUGGINGFACE_API_KEY || "hf",
      baseURL,
    });
    // TEI ignores the model field; default mirrors the Python provider.
    this.model = config.model || "tei";
  }

  async embed(text: string): Promise<number[]> {
    const response = await this.openai.embeddings.create({
      model: this.model,

View on GitHub (pinned to 001c235229)

Solutions

Set the URL in config: embedder: { provider: 'huggingface', config: { huggingfaceBaseUrl: 'http://localhost:8080/v1', apiKey: 'hf' } }
Or export HUGGINGFACE_BASE_URL=http://localhost:8080/v1 in the runtime environment
Verify the TEI server is up: curl $HUGGINGFACE_BASE_URL/models — it must expose the OpenAI-compatible /embeddings route

Example fix

// before
embedder: { provider: 'huggingface', config: { apiKey: 'hf_xxx', model: 'tei' } }

// after
embedder: {
  provider: 'huggingface',
  config: { huggingfaceBaseUrl: 'http://localhost:8080/v1', apiKey: 'hf_xxx' },
}

Defensive patterns

Strategy: validation

Validate before calling

const HF_BASE = process.env.HUGGINGFACE_BASE_URL ?? 'http://localhost:8080/v1';
if (!HF_BASE) throw new Error('TEI base URL required for huggingface embedder');
embedder: { provider: 'huggingface', config: { huggingfaceBaseUrl: HF_BASE } }

Type guard

const isTeiBaseUrl = (u: unknown): u is string =>
  typeof u === 'string' && /^https?:\/\//.test(u);

Prevention

Always set huggingfaceBaseUrl explicitly in config; do not depend on ambient env vars in deployed environments
Remember this provider targets a self-hosted TEI server, not the HF Hub — provision the server first
Add a startup curl/health check against $BASE/models to confirm the server is reachable before building Memory

When it happens

Trigger: EmbeddingConfig with only apiKey and model (copied from the OpenAI provider); HUGGINGFACE_BASE_URL set in the local shell but not in the deployed environment; base URL placed under modelProperties where this embedder does not read it.

Common situations: Running TEI in Docker (http://localhost:8080) locally but forgetting to configure the URL in Kubernetes/Vercel; assuming the provider calls hf.co inference endpoints (it targets TEI servers); env var named differently (HF_API_BASE vs HUGGINGFACE_BASE_URL).

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/224e025b5515c76f. Report an issue: GitHub.