MemPalace/mempalace · error · ImportError

EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and

Error message

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

What it means

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.

Source

Thrown at mempalace/embedding.py:332

        self._output_idx = None
        # Instances are shared across threads via _EF_CACHE; serialize the
        # one-time model load so concurrent cold calls cannot build (and
        # transiently hold) two full model sessions.
        self._load_lock = threading.Lock()

    def _lazy_load(self) -> None:
        if self._session is not None:
            return
        with self._load_lock:
            if self._session is not None:
                return
            try:
                import numpy as np
                import onnxruntime as ort
                from huggingface_hub import hf_hub_download
                from tokenizers import Tokenizer
            except ImportError as e:
                raise ImportError(
                    "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"
                ) from e

            logger.info(
                "Downloading %s/%s (cached after first run)…",
                _EMBEDDINGGEMMA_REPO,
                _EMBEDDINGGEMMA_ONNX,
            )
            model_path = hf_hub_download(
                _EMBEDDINGGEMMA_REPO, subfolder="onnx", filename=_EMBEDDINGGEMMA_ONNX
            )
            hf_hub_download(
                _EMBEDDINGGEMMA_REPO, subfolder="onnx", filename=_EMBEDDINGGEMMA_ONNX + "_data"
            )
            tok_path = hf_hub_download(_EMBEDDINGGEMMA_REPO, filename="tokenizer.json")

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Run: pip install --upgrade --force-reinstall mempalace (as the message says) to restore the pinned dependency set
2. If using uv: uv sync --extra dev or uv sync to realign the lockfile
3. Check which import actually failed by reading the chained cause (__cause__ / 'from e'); install just that package if a full reinstall is too disruptive
4. Verify with: python -c "import numpy, onnxruntime, huggingface_hub, tokenizers"
5. If onnxruntime has no wheel for your platform, switch to the openai-compat embedding backend or upgrade Python to a version with wheel support

Example fix

# before: broken env
python -c "from mempalace.embedding import get_embedding_function; get_embedding_function()"
# ImportError: EmbeddinggemmaONNX requires huggingface_hub, tokenizers, and numpy ...

# after: repair env
pip install --upgrade --force-reinstall mempalace
python -c "import numpy, onnxruntime, huggingface_hub, tokenizers; print('ok')"

def embedding_deps_available() -> bool:
    for mod in ("numpy", "onnxruntime", "huggingface_hub", "tokenizers"):
        try:
            __import__(mod)
        except ImportError:
            return False
    return True

# run before ingest; surface a friendly setup message if False

try:
    ef = get_embedding_function()
except ImportError as e:
    print("Run: pip install --upgrade --force-reinstall mempalace")
    print("Original cause:", e.__cause__)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• query input must be a non-empty list
• embedding must be a non-empty 1D vector
• LLM_ENDPOINT must use http:// or https:// (got scheme {schem
• Embedding API request to {self._url} failed: {e}. Check that
• Embedding API at {self._url} returned a non-object response:

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