MemPalace/mempalace · error · ValueError

embedding_model='openai-compat' requires a model — set embed

Error message

embedding_model='openai-compat' requires a model — set embedding_api_model in ~/.mempalace/config.json or the MEMPALACE_EMBEDDING_API_MODEL env var

What it means

Raised by get_embedding_function immediately after the URL check when embedding_model='openai-compat' has an endpoint but embedding_api_model is empty. The remote server needs an explicit model identifier to route the request, and mempalace will not invent one — embedding with the wrong model would make all vectors incompatible with future queries. Config surfaces named in the message: embedding_api_model in ~/.mempalace/config.json or MEMPALACE_EMBEDDING_API_MODEL.

Source

Thrown at mempalace/embedding.py:656

        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:
            return cached
        ef = OpenAICompatEmbeddingFunction(base_url=url, model=api_model, api_key=api_key)
        _EF_CACHE[cache_key] = ef
        logger.info(
            "Embedding function initialized (openai-compat url=%s model=%s)", url, api_model
        )
        return ef

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Set the model the server hosts: export MEMPALACE_EMBEDDING_API_MODEL=text-embedding-nomic-embed-text-v1.5 or "embedding_api_model": "..." in config.json
2. List available models: curl http://<host:port>/v1/models and copy the exact id
3. Do not confuse with MEMPALACE_EMBEDDING_MODEL (that selects the backend, value 'openai-compat') — the API model goes in MEMPALACE_EMBEDDING_API_MODEL
4. Restart any long-lived MCP server process after the config change

Example fix

# before
export MEMPALACE_EMBEDDING_MODEL=openai-compat
export MEMPALACE_EMBEDDING_API_URL=http://127.0.0.1:1234
# after (add the third var)
export MEMPALACE_EMBEDDING_MODEL=openai-compat
export MEMPALACE_EMBEDDING_API_URL=http://127.0.0.1:1234
export MEMPALACE_EMBEDDING_API_MODEL=text-embedding-nomic-embed-text-v1.5

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

try:
    ef = get_embedding_function()
except ValueError as e:
    if "requires a model" in str(e):
        sys.exit("Set MEMPALACE_EMBEDDING_API_MODEL (see the server's /v1/models)")

When it happens

Trigger: Configuring openai-compat with embedding_api_url only. The two settings are paired; if you fix error 230 (missing URL) this is the next error hit in the same code path when the model key is also absent.

Common situations: Following a tutorial that sets only the URL; switching servers and reusing an old config that predates the api_model key; assuming the server has a usable default model; env var name typos (MEMPALACE_EMBEDDING_MODEL set instead of _API_MODEL).

Related errors

• embedding_model='openai-compat' requires an endpoint — set e
• Embedding API request to {self._url} failed: {e}. Check that
• update requires at least one of documents, metadatas, embedd
• query requires exactly one of query_texts or query_embedding
• query input must be a non-empty list

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