headroomlabs-ai/headroom · error · ConnectionError

Ollama API error: {e}

Error message

Ollama API error: {e}

What it means

Inside OllamaEmbedder's retry loop, transient failures — httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError — are retried with backoff, but any other exception is immediately wrapped in ConnectionError('Ollama API error: {e}') with the original chained. This branch means a non-transient failure such as a 404 from an unknown model, a malformed request, or a response that isn't valid JSON for the expected schema.

Source

Thrown at headroom/memory/adapters/embedders.py:932

                # Detect dimension from first successful response
                if self._detected_dimension is None:
                    self._detected_dimension = len(embedding)

                return embedding

            except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPStatusError) as e:
                last_error = e
                delay = self.RETRY_DELAY_BASE * (2**attempt)
                logger.warning(
                    f"Ollama API error (attempt {attempt + 1}/{self._max_retries}): {e}. "
                    f"Retrying in {delay:.1f}s..."
                )
                await asyncio.sleep(delay)

            except Exception as e:
                # Non-retryable error
                raise ConnectionError(f"Ollama API error: {e}") from e

        # All retries exhausted
        raise ConnectionError(
            f"Ollama API failed after {self._max_retries} retries: {last_error}"
        ) from last_error

    async def embed(self, text: str) -> np.ndarray:
        """Generate an embedding for a single text.

        Args:
            text: The text to embed.

        Returns:
            Normalized embedding vector as float32 numpy array.

        Raises:
            ConnectionError: If API call fails after retries.
        """

View on GitHub (pinned to 322425c43b)

Solutions

1. Check the chained __cause__ — a 404 'model not found' means you must pull it: `ollama pull nomic-embed-text`.
2. Verify the server is the version you expect: curl http://localhost:11434/api/tags and confirm the model is listed.
3. Match the model name in OllamaEmbedder(model_name=...) exactly to `ollama list` output.
4. Upgrade/downgrade Ollama to match the API shape headroom targets.
5. Do not retry — this class is non-retryable by design.

Example fix

# before
emb = OllamaEmbedder(model_name="nomic-embed")  # 404 -> ConnectionError
await emb.embed("hi")

# after (shell)
ollama pull nomic-embed-text
# python
emb = OllamaEmbedder(model_name="nomic-embed-text")

import httpx

def ollama_model_ready(base_url: str, model: str) -> bool:
    """True if the local Ollama server lists the requested model."""
    try:
        tags = httpx.get(f"{base_url}/api/tags", timeout=5).json()
        return any(m["name"] == model for m in tags.get("models", []))
    except httpx.HTTPError:
        return False

if not ollama_model_ready("http://localhost:11434", "nomic-embed-text"):
    raise SystemExit("ollama pull nomic-embed-text before embedding")

try:
    vec = await emb.embed(text)
except ConnectionError as e:
    if "Ollama API error" in str(e) and "404" in str(e.__cause__):
        raise SystemExit("model not pulled: run `ollama pull <model>`") from e
    raise

When it happens

Trigger: Calling embed()/embed_batch() against a local Ollama server where the configured embedding model (e.g. nomic-embed-text) has not been pulled, the model returns an unexpected payload, or the request body doesn't match the Ollama version's /api/embed contract.

Common situations: Fresh Ollama install without `ollama pull nomic-embed-text`; Ollama version mismatch (old /api/embeddings vs newer /api/embed endpoint shapes); model name typo in config; GPU Ollama crashing mid-request producing a non-HTTP error.

Related errors

• OpenAI API error: {e}
• Ollama API failed after {self._max_retries} retries: {last_e
• OpenAI API failed after {self._max_retries} retries: {last_e
• httpx is required for OllamaEmbedder. Install it with: pip i
• ollama package required. Install with: pip install ollama

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