headroomlabs-ai/headroom · error · ValueError

openai_api_key is required when using OpenAI embedder backen

Error message

openai_api_key is required when using OpenAI embedder backend

What it means

ValueError raised in MemoryConfig.__post_init__ when embedder_backend is EmbedderBackend.OPENAI but openai_api_key is falsy. The local vector memory system calls the OpenAI embeddings API for every store/search, so it refuses to construct without a key rather than failing later at request time.

Source

Thrown at headroom/memory/config.py:154

        if self.vector_dimension < 1:
            raise ValueError(f"vector_dimension must be positive, got {self.vector_dimension}")

        if self.hnsw_ef_construction < 1:
            raise ValueError(
                f"hnsw_ef_construction must be positive, got {self.hnsw_ef_construction}"
            )

        if self.hnsw_m < 1:
            raise ValueError(f"hnsw_m must be positive, got {self.hnsw_m}")

        if self.hnsw_ef_search < 1:
            raise ValueError(f"hnsw_ef_search must be positive, got {self.hnsw_ef_search}")

        if self.cache_max_size < 1:
            raise ValueError(f"cache_max_size must be positive, got {self.cache_max_size}")

        if self.embedder_backend == EmbedderBackend.OPENAI and not self.openai_api_key:
            raise ValueError("openai_api_key is required when using OpenAI embedder backend")

        # Ensure db_path is a Path object
        if isinstance(self.db_path, str):
            self.db_path = Path(self.db_path)

View on GitHub (pinned to 322425c43b)

Solutions

1. Provide the key: MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=os.environ['OPENAI_API_KEY'])
2. Or export OPENAI_API_KEY in the runtime environment of the process
3. If you want offline/no-API-key operation, switch to a local embedder backend (EmbedderBackend.LOCAL or equivalent)

Example fix

# before
cfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI)
# ValueError: openai_api_key is required when using OpenAI embedder backend

# after
import os
cfg = MemoryConfig(
    embedder_backend=EmbedderBackend.OPENAI,
    openai_api_key=os.environ['OPENAI_API_KEY'],
)

import os

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise SystemExit('OPENAI_API_KEY required for the OpenAI embedder backend')
cfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=api_key)

try:
    cfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=key)
except ValueError as e:
    if 'openai_api_key is required' in str(e):
        cfg = MemoryConfig(embedder_backend=EmbedderBackend.LOCAL)  # offline fallback
    else:
        raise

When it happens

Trigger: MemoryConfig(embedder_backend=EmbedderBackend.OPENAI) with openai_api_key missing/empty — usually the env var (OPENAI_API_KEY) wasn't set in the process or wasn't passed into the config explicitly.

Common situations: Deployments where the key exists in the shell but not in the service's env; .env file not loaded; key passed to a different field name than openai_api_key; local embedder intended but OPENAI left as default.

Related errors

• api_key is required for cloud mode
• vector_dimension must be positive, got {self.vector_dimensio
• default_importance must be 0.0-1.0, got {self.default_import
• dedup_similarity_threshold must be 0.0-1.0, got {self.dedup_
• hnsw_ef_construction must be positive, got {self.hnsw_ef_con

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