headroomlabs-ai/headroom · error · RuntimeError

EmbeddingScorer requires fastembed. Install with: pip instal

Error message

EmbeddingScorer requires fastembed. Install with: pip install headroom[relevance]

What it means

Raised by EmbeddingScorer._get_model() when the fastembed package is not installed. The scorer guards model loading behind is_available() so the constructor succeeds even in installs without fastembed, and this error appears only when you actually try to load the model.

Source

Thrown at headroom/relevance/embedding.py:167

        """
        try:
            import fastembed  # noqa: F401

            return True
        except ImportError:
            return False

    def _get_model(self) -> TextEmbedding:
        """Get or load the fastembed text embedding model.

        Returns:
            Loaded TextEmbedding model.

        Raises:
            RuntimeError: If fastembed is not installed.
        """
        if not self.is_available():
            raise RuntimeError(
                "EmbeddingScorer requires fastembed. Install with: pip install headroom[relevance]"
            )

        if self._model is None:
            from fastembed import TextEmbedding

            revision = _pinned_revision(self.model_name)
            if revision is not None:
                # fastembed forwards **kwargs to snapshot_download(revision=...).
                self._model = TextEmbedding(model_name=self.model_name, revision=revision)
            else:
                self._model = TextEmbedding(model_name=self.model_name)
        return self._model

    def _encode(self, texts: list[str]):
        """Encode texts to embeddings via fastembed.

        fastembed's `embed` returns an iterator yielding numpy arrays

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: pip install 'headroom[relevance]'.
2. Construct scorers via create_scorer('embedding') so availability is checked up front with a clearer error.
3. Prefer the bm25 tier when embeddings are not required.

Example fix

# before
scorer = EmbeddingScorer()
vec = next(scorer._get_model().embed(['hi']))

# after
# pip install 'headroom[relevance]'
from headroom.relevance import create_scorer
scorer = create_scorer('embedding')

from headroom.relevance import EmbeddingScorer, create_scorer

def build_scorer(**kw):
    tier = 'embedding' if EmbeddingScorer.is_available() else 'bm25'
    return create_scorer(tier, **kw)

from headroom.relevance import EmbeddingScorer

def embedding_model_available() -> bool:
    return bool(EmbeddingScorer.is_available())

try:
    scorer = create_scorer('embedding', **kwargs)
except RuntimeError as e:
    if 'fastembed' in str(e):
        scorer = create_scorer('bm25', **kwargs)
    else:
        raise

When it happens

Trigger: Constructing an EmbeddingScorer directly (bypassing create_scorer's check) and calling any method that loads the model, in an environment without fastembed.

Common situations: Instantiating EmbeddingScorer directly instead of via create_scorer(); pruning 'unused' packages from a Docker layer; deploying to a runtime environment different from the build one.

Related errors

• numpy is required for EmbeddingScorer. Install with: pip ins
• jinja2 is required for report generation. Install with: pip
• EmbeddingScorer requires sentence-transformers. Install with
• No optimizer registered for '{key}'. Available: {available}
• httpx is required for Headroom Cloud mode: pip install httpx

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/63c8ce1c1e2f1759. Report an issue: GitHub.