{"record":{"id":"dd855ffe524af70e","repo":"MemPalace/mempalace","slug":"embedding-model-openai-compat-requires-a-model","errorCode":null,"errorMessage":"embedding_model='openai-compat' requires a model — set embedding_api_model in ~/.mempalace/config.json or the MEMPALACE_EMBEDDING_API_MODEL env var","messagePattern":"embedding_model='openai-compat' requires a model — set embedding_api_model in ~/\\.mempalace/config\\.json or the MEMPALACE_EMBEDDING_API_MODEL env var","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mempalace/embedding.py","lineNumber":656,"sourceCode":"        if model is None:\n            model = cfg.embedding_model\n\n    # OpenAI-compatible embedding API: bypasses local ONNX entirely. Checked\n    # before device→provider resolution since it needs no hardware accelerator.\n    if model == \"openai-compat\":\n        from .config import MempalaceConfig\n\n        cfg = MempalaceConfig()\n        url = cfg.embedding_api_url\n        if not url:\n            raise ValueError(\n                \"embedding_model='openai-compat' requires an endpoint — set \"\n                \"embedding_api_url in ~/.mempalace/config.json or the \"\n                \"MEMPALACE_EMBEDDING_API_URL env var (e.g. http://host:port)\"\n            )\n        api_model = cfg.embedding_api_model\n        if not api_model:\n            raise ValueError(\n                \"embedding_model='openai-compat' requires a model — set \"\n                \"embedding_api_model in ~/.mempalace/config.json or the \"\n                \"MEMPALACE_EMBEDDING_API_MODEL env var\"\n            )\n        api_key = cfg.embedding_api_key\n        # Include a fingerprint of the key (never the raw secret) so a token\n        # rotation busts the cache in long-lived processes (e.g. MCP server).\n        key_fp = hashlib.sha256((api_key or \"\").encode(\"utf-8\")).hexdigest()[:16]\n        cache_key = (\"openai-compat\", url, api_model, key_fp)\n        cached = _EF_CACHE.get(cache_key)\n        if cached is not None:\n            return cached\n        ef = OpenAICompatEmbeddingFunction(base_url=url, model=api_model, api_key=api_key)\n        _EF_CACHE[cache_key] = ef\n        logger.info(\n            \"Embedding function initialized (openai-compat url=%s model=%s)\", url, api_model\n        )\n        return ef","sourceCodeStart":638,"sourceCodeEnd":674,"githubUrl":"https://github.com/MemPalace/mempalace/blob/06cb6987f02610784fefbad4b2bd5d026d164ba6/mempalace/embedding.py#L638-L674","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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","List available models: curl http://<host:port>/v1/models and copy the exact id","Do not confuse with MEMPALACE_EMBEDDING_MODEL (that selects the backend, value 'openai-compat') — the API model goes in MEMPALACE_EMBEDDING_API_MODEL","Restart any long-lived MCP server process after the config change"],"exampleFix":"# before\nexport MEMPALACE_EMBEDDING_MODEL=openai-compat\nexport MEMPALACE_EMBEDDING_API_URL=http://127.0.0.1:1234\n# after (add the third var)\nexport MEMPALACE_EMBEDDING_MODEL=openai-compat\nexport MEMPALACE_EMBEDDING_API_URL=http://127.0.0.1:1234\nexport MEMPALACE_EMBEDDING_API_MODEL=text-embedding-nomic-embed-text-v1.5","handlingStrategy":"validation","validationCode":"cfg = MempalaceConfig()\nassert cfg.embedding_model != \"openai-compat\" or cfg.embedding_api_model, (\n    \"openai-compat requires MEMPALACE_EMBEDDING_API_MODEL / embedding_api_model\"\n)","typeGuard":null,"tryCatchPattern":"try:\n    ef = get_embedding_function()\nexcept ValueError as e:\n    if \"requires a model\" in str(e):\n        sys.exit(\"Set MEMPALACE_EMBEDDING_API_MODEL (see the server's /v1/models)\")","preventionTips":["Copy the model id verbatim from curl http://host:port/v1/models","Do not confuse MEMPALACE_EMBEDDING_MODEL (backend selector) with MEMPALACE_EMBEDDING_API_MODEL","Restart MCP servers after env-var changes"],"tags":["config","embedding","openai-compat","setup"],"backgroundTag":null,"analyzedSha":"06cb6987f02610784fefbad4b2bd5d026d164ba6","analyzedAt":"2026-08-15T03:03:36.213Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}