{"record":{"id":"fb13132256d6bb61","repo":"MemPalace/mempalace","slug":"embeddinggemmaonnx-requires-huggingface-hub-token","errorCode":null,"errorMessage":"EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and numpy — these ship with mempalace core, so this error usually means one was uninstalled or pinned to an incompatible version. Reinstall with: pip install --upgrade --force-reinstall mempalace","messagePattern":"EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and numpy — these ship with mempalace core, so this error usually means one was uninstalled or pinned to an incompatible version\\. Reinstall with: pip install --upgrade --force-reinstall mempalace","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"mempalace/embedding.py","lineNumber":332,"sourceCode":"        self._output_idx = None\n        # Instances are shared across threads via _EF_CACHE; serialize the\n        # one-time model load so concurrent cold calls cannot build (and\n        # transiently hold) two full model sessions.\n        self._load_lock = threading.Lock()\n\n    def _lazy_load(self) -> None:\n        if self._session is not None:\n            return\n        with self._load_lock:\n            if self._session is not None:\n                return\n            try:\n                import numpy as np\n                import onnxruntime as ort\n                from huggingface_hub import hf_hub_download\n                from tokenizers import Tokenizer\n            except ImportError as e:\n                raise ImportError(\n                    \"EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and \"\n                    \"numpy — these ship with mempalace core, so this error usually \"\n                    \"means one was uninstalled or pinned to an incompatible version. \"\n                    \"Reinstall with: pip install --upgrade --force-reinstall mempalace\"\n                ) from e\n\n            logger.info(\n                \"Downloading %s/%s (cached after first run)…\",\n                _EMBEDDINGGEMMA_REPO,\n                _EMBEDDINGGEMMA_ONNX,\n            )\n            model_path = hf_hub_download(\n                _EMBEDDINGGEMMA_REPO, subfolder=\"onnx\", filename=_EMBEDDINGGEMMA_ONNX\n            )\n            hf_hub_download(\n                _EMBEDDINGGEMMA_REPO, subfolder=\"onnx\", filename=_EMBEDDINGGEMMA_ONNX + \"_data\"\n            )\n            tok_path = hf_hub_download(_EMBEDDINGGEMMA_REPO, filename=\"tokenizer.json\")","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/MemPalace/mempalace/blob/06cb6987f02610784fefbad4b2bd5d026d164ba6/mempalace/embedding.py#L314-L350","documentation":"Raised by EmbeddinggemmaONNX._lazy_load when the deferred imports numpy, onnxruntime, huggingface_hub, or tokenizers fail. These are declared core dependencies of mempalace, so the error message states the likely root cause explicitly: one package was uninstalled or version-pinned incompatibly (e.g. by another tool sharing the venv), and recommends a force reinstall. The ImportError is chained from the original so the exact missing module stays visible.","triggerScenarios":"Instantiating EmbeddinggemmaONNX (directly or via get_embedding_function with a local ONNX model setting) in an environment where pip uninstall numpy, a requirements.txt pin conflict, or a conda/pip mix removed or broke one of the four packages. Also triggered when onnxruntime is missing on unsupported platforms.","commonSituations":"A sibling project pinned numpy<2 in a shared venv; installing mempalace with --no-deps; running under a system Python where onnxruntime was never installed; a broken half-upgraded environment after pip install -U of an unrelated package.","solutions":["Run: pip install --upgrade --force-reinstall mempalace (as the message says) to restore the pinned dependency set","If using uv: uv sync --extra dev or uv sync to realign the lockfile","Check which import actually failed by reading the chained cause (__cause__ / 'from e'); install just that package if a full reinstall is too disruptive","Verify with: python -c \"import numpy, onnxruntime, huggingface_hub, tokenizers\"","If onnxruntime has no wheel for your platform, switch to the openai-compat embedding backend or upgrade Python to a version with wheel support"],"exampleFix":"# before: broken env\npython -c \"from mempalace.embedding import get_embedding_function; get_embedding_function()\"\n# ImportError: EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and numpy ...\n\n# after: repair env\npip install --upgrade --force-reinstall mempalace\npython -c \"import numpy, onnxruntime, huggingface_hub, tokenizers; print('ok')\"","handlingStrategy":"validation","validationCode":"def embedding_deps_available() -> bool:\n    for mod in (\"numpy\", \"onnxruntime\", \"huggingface_hub\", \"tokenizers\"):\n        try:\n            __import__(mod)\n        except ImportError:\n            return False\n    return True\n\n# run before ingest; surface a friendly setup message if False","typeGuard":null,"tryCatchPattern":"try:\n    ef = get_embedding_function()\nexcept ImportError as e:\n    print(\"Run: pip install --upgrade --force-reinstall mempalace\")\n    print(\"Original cause:\", e.__cause__)","preventionTips":["Pin mempalace and its deps in a dedicated venv; avoid sharing the venv with projects that pin numpy<2","Use uv sync (lockfile) instead of ad-hoc pip install","Add a startup smoke test: python -c \"import numpy, onnxruntime, huggingface_hub, tokenizers\"","After any pip install/uninstall in a shared env, re-run the smoke test"],"tags":["dependencies","import","onnx","embedding","environment"],"backgroundTag":null,"analyzedSha":"06cb6987f02610784fefbad4b2bd5d026d164ba6","analyzedAt":"2026-08-15T03:03:36.213Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}