LLMRouter.embed(): surface actionable error when Ollama model is not pulled #60

New issue

Closed

opened 2026-05-05 14:46:14 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-05-05 14:46:14 -07:00

Owner

Problem

When LLMRouter.embed() is called with an Ollama backend and the configured embedding model has not been pulled, the error surfaces as:

All LLM backends exhausted for embed()

This is opaque. The user has no idea that the fix is ollama pull nomic-embed-text.

Desired behaviour

Before calling the Ollama embedding endpoint, do a lightweight pre-flight check against GET /api/tags (already reachable since _is_reachable() hits Ollama). If the configured embedding_model is not in the tags list, raise a RuntimeError with an actionable message:

Ollama embedding model "nomic-embed-text" is not pulled.
Fix: ollama pull nomic-embed-text

This check should be fast (one cached HTTP call) and only happen on the first embed attempt.

Context

Discovered while debugging pagepiper cloud ingest. Ollama was running and had many models but not the configured embed model. Took several round-trips to diagnose.

Related: the graceful-degradation pattern in pagepiper ingest_pdf.py / ingest_epub.py catches this RuntimeError and continues BM25-only, logging the actionable message from above. A good error string here directly improves the log output operators see.

Labels

enhancement, llm, dx

## Problem When `LLMRouter.embed()` is called with an Ollama backend and the configured embedding model has not been pulled, the error surfaces as: ``` All LLM backends exhausted for embed() ``` This is opaque. The user has no idea that the fix is `ollama pull nomic-embed-text`. ## Desired behaviour Before calling the Ollama embedding endpoint, do a lightweight pre-flight check against `GET /api/tags` (already reachable since `_is_reachable()` hits Ollama). If the configured `embedding_model` is not in the tags list, raise a `RuntimeError` with an actionable message: ``` Ollama embedding model "nomic-embed-text" is not pulled. Fix: ollama pull nomic-embed-text ``` This check should be fast (one cached HTTP call) and only happen on the first embed attempt. ## Context Discovered while debugging pagepiper cloud ingest. Ollama was running and had many models but not the configured embed model. Took several round-trips to diagnose. Related: the graceful-degradation pattern in pagepiper `ingest_pdf.py` / `ingest_epub.py` catches this `RuntimeError` and continues BM25-only, logging the actionable message from above. A good error string here directly improves the log output operators see. ## Labels - enhancement, llm, dx