MemPalace/mempalace · error · ValueError

embedding_model='openai-compat' requires an endpoint — set e

Error message

embedding_model='openai-compat' requires an endpoint — set embedding_api_url in ~/.mempalace/config.json or the MEMPALACE_EMBEDDING_API_URL env var (e.g. http://host:port)

What it means

Raised by get_embedding_function when embedding_model is 'openai-compat' but no endpoint URL is configured. The openai-compat backend bypasses local ONNX entirely and needs a base URL; it reads MempalaceConfig.embedding_api_url (backed by MEMPALACE_EMBEDDING_API_URL env var or ~/.mempalace/config.json) and refuses to guess a default like localhost, since silently hitting the wrong server would embed everything against a mismatched model and poison the store.

Source

Thrown at mempalace/embedding.py:649

    """
    if device is None or model is None:
        from .config import MempalaceConfig

        cfg = MempalaceConfig()
        if device is None:
            device = cfg.embedding_device
        if model is None:
            model = cfg.embedding_model

    # OpenAI-compatible embedding API: bypasses local ONNX entirely. Checked
    # before device→provider resolution since it needs no hardware accelerator.
    if model == "openai-compat":
        from .config import MempalaceConfig

        cfg = MempalaceConfig()
        url = cfg.embedding_api_url
        if not url:
            raise ValueError(
                "embedding_model='openai-compat' requires an endpoint — set "
                "embedding_api_url in ~/.mempalace/config.json or the "
                "MEMPALACE_EMBEDDING_API_URL env var (e.g. http://host:port)"
            )
        api_model = cfg.embedding_api_model
        if not api_model:
            raise ValueError(
                "embedding_model='openai-compat' requires a model — set "
                "embedding_api_model in ~/.mempalace/config.json or the "
                "MEMPALACE_EMBEDDING_API_MODEL env var"
            )
        api_key = cfg.embedding_api_key
        # Include a fingerprint of the key (never the raw secret) so a token
        # rotation busts the cache in long-lived processes (e.g. MCP server).
        key_fp = hashlib.sha256((api_key or "").encode("utf-8")).hexdigest()[:16]
        cache_key = ("openai-compat", url, api_model, key_fp)
        cached = _EF_CACHE.get(cache_key)
        if cached is not None:

View on GitHub (pinned to 06cb6987f0)

Solutions

Set the URL: export MEMPALACE_EMBEDDING_API_URL=http://127.0.0.1:1234 or add "embedding_api_url": "http://127.0.0.1:1234" to ~/.mempalace/config.json
Also set the model (MEMPALACE_EMBEDDING_API_MODEL) — it is the next required key and will raise immediately after this one if missing
Restart the MCP server / long-lived process after changing env vars so it picks up the new value
Verify with: python -c "from mempalace.config import MempalaceConfig; print(MempalaceConfig().embedding_api_url)"

Example fix

# ~/.mempalace/config.json — before
{"embedding_model": "openai-compat"}
# after
{
  "embedding_model": "openai-compat",
  "embedding_api_url": "http://127.0.0.1:1234",
  "embedding_api_model": "text-embedding-nomic-embed-text-v1.5"
}

Defensive patterns

Strategy: validation

Validate before calling

from mempalace.config import MempalaceConfig

cfg = MempalaceConfig()
assert cfg.embedding_model != "openai-compat" or cfg.embedding_api_url, (
    "openai-compat requires MEMPALACE_EMBEDDING_API_URL / embedding_api_url"
)

Try / catch

try:
    ef = get_embedding_function()
except ValueError as e:
    if "requires an endpoint" in str(e):
        sys.exit("Set MEMPALACE_EMBEDDING_API_URL=http://host:port and retry")

Prevention

Treat openai-compat as a triple: model + api_url + api_model — configure all three at once
Put config in ~/.mempalace/config.json rather than shell env vars for long-lived MCP servers
Print the effective config at pipeline startup to catch missing keys early

When it happens

Trigger: Setting MEMPALACE_EMBEDDING_MODEL=openai-compat (or embedding_model='openai-compat' in config.json) without also setting MEMPALACE_EMBEDDING_API_URL or embedding_api_url. Typically after switching from the default local ONNX backend to a server-based one and forgetting the second required key.

Common situations: Migrating to LM Studio/vLLM/Ollama embeddings and setting only the model key; assuming a default localhost URL exists; config.json edited by hand with a typo'd key (embedding_api instead of embedding_api_url); env var set in one shell but the process (MCP server) launched from another.

Related errors

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/34ee7b9074d05b9f. Report an issue: GitHub.