headroomlabs-ai/headroom · error · ValueError

Unknown embedder backend: {config.embedder_backend}

Error message

Unknown embedder backend: {config.embedder_backend}

What it means

`_create_embedder` handles OPENAI and OLLAMA embedder backends explicitly; anything else falls through to a defensive ValueError. Like the store fallback, this normally means config.embedder_backend is not a genuine EmbedderBackend enum member, or the installed headroom version's enum has members this factory branch does not handle.

Source

Thrown at headroom/memory/factory.py:217

            embedder = OnnxLocalEmbedder()

        elif config.embedder_backend == EmbedderBackend.OPENAI:
            from headroom.memory.adapters.embedders import OpenAIEmbedder

            embedder = OpenAIEmbedder(
                api_key=config.openai_api_key,
                model_name=config.embedder_model,
            )

        elif config.embedder_backend == EmbedderBackend.OLLAMA:
            from headroom.memory.adapters.embedders import OllamaEmbedder

            embedder = OllamaEmbedder(
                base_url=config.ollama_base_url,
                model_name=config.embedder_model,
            )
        else:
            raise ValueError(f"Unknown embedder backend: {config.embedder_backend}")

        _EMBEDDER_CACHE[key] = embedder
        return embedder


def _reset_embedder_cache_for_tests() -> None:
    """Clear the process-wide embedder cache. Test-only seam."""

    with _EMBEDDER_CACHE_LOCK:
        _EMBEDDER_CACHE.clear()


def _create_vector_index(config: MemoryConfig) -> VectorIndex:
    """Create a vector index backend.

    Args:
        config: Memory system configuration.

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the field to a real enum member: config.embedder_backend = EmbedderBackend.OPENAI (and provide openai_api_key) or EmbedderBackend.OLLAMA
2. Reinstall headroom with matching versions across extras so enum and factory agree
3. Coerce deserialized values explicitly with EmbedderBackend(raw) and fail at config-load time

Example fix

# before
config = MemoryConfig(embedder_backend="openai")

# after
from headroom.memory.config import EmbedderBackend
config = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI,
                      openai_api_key=os.environ["OPENAI_API_KEY"])

from headroom.memory.config import EmbedderBackend
assert isinstance(config.embedder_backend, EmbedderBackend), \
    f"embedder_backend must be EmbedderBackend, got {config.embedder_backend!r}"

def is_embedder_backend(v: object) -> bool:
    return isinstance(v, EmbedderBackend)

try:
    system = await create_memory_system(config)
except ValueError as e:
    if "Unknown embedder backend" in str(e):
        raise ConfigError("embedder_backend not a valid EmbedderBackend") from e
    raise

When it happens

Trigger: Passing a string ("openai") or a mock object as embedder_backend; a version-skew where the enum gained a member (e.g. ONNX) that the installed factory build does not construct.

Common situations: Mixed headroom-ai package versions in one environment; configs deserialized from YAML leaving a plain string; tests stubbing the enum.

Related errors

• OpenAI API key required. Provide api_key parameter or set OP
• Unknown store backend: {config.store_backend}
• openai_api_key is required for OpenAI embedder
• bedrock_eventstream_parse_failed
• bedrock_eventstream_crc_mismatch

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