headroomlabs-ai/headroom · error · ValueError

OpenAI API key required. Provide api_key parameter or set OP

Error message

OpenAI API key required. Provide api_key parameter or set OPENAI_API_KEY environment variable.

What it means

OpenAIEmbedder.__init__ resolves the API key as api_key argument or falls back to the OPENAI_API_KEY environment variable; if neither yields a non-empty string it raises ValueError immediately, before any network call, so misconfigured deployments fail fast at construction rather than mid-request.

Source

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

        max_retries: int | None = None,
    ) -> None:
        """Initialize the OpenAI embedder.

        Args:
            api_key: OpenAI API key. If not provided, will use OPENAI_API_KEY
                    environment variable.
            model_name: Model to use. Defaults to "text-embedding-3-small".
            max_retries: Maximum number of retries for transient failures.

        Raises:
            ImportError: If openai library is not installed.
            ValueError: If no API key is provided or found in environment.
        """
        self._check_dependencies()

        self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
        if not self._api_key:
            raise ValueError(
                "OpenAI API key required. Provide api_key parameter or set "
                "OPENAI_API_KEY environment variable."
            )

        self._model_name = model_name or self.DEFAULT_MODEL
        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES
        self._client = None

    def _check_dependencies(self) -> None:
        """Check that required dependencies are installed."""
        try:
            import openai  # noqa: F401
        except ImportError as e:
            raise ImportError(
                "openai is required for OpenAIEmbedder. Install it with: pip install openai"
            ) from e

    @cached_property

View on GitHub (pinned to 322425c43b)

Solutions

Export the variable in the process that runs your code: export OPENAI_API_KEY=sk-... (or add it via docker -e / CI secret).
Or pass it explicitly: OpenAIEmbedder(api_key=os.environ['MY_KEY']).
Verify with print(bool(os.environ.get('OPENAI_API_KEY'))) in the exact runtime context.
Use a secrets manager / devkey flow rather than hardcoding the key.

Example fix

# before
emb = OpenAIEmbedder()  # ValueError: OpenAI API key required

# after
import os
emb = OpenAIEmbedder(api_key=os.environ["OPENAI_API_KEY"])  # var actually set in this process

Defensive patterns

Strategy: validation

Validate before calling

import os

api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise SystemExit("OPENAI_API_KEY not set in this process; export it or pass api_key=")

Try / catch

try:
    emb = OpenAIEmbedder(api_key=os.environ.get("OPENAI_API_KEY"))
except ValueError as e:
    if "API key" in str(e):
        raise SystemExit("OpenAI credentials missing; configure secret and restart") from e
    raise

Prevention

Inject secrets via the environment of the exact process (docker -e, k8s secrets, systemd Environment=).
Fail fast at startup: check required env vars in a preflight block, not when the first embed happens.
Never hardcode keys as a 'fix'; route them through a secrets manager.

When it happens

Trigger: Constructing OpenAIEmbedder() with no api_key param while OPENAI_API_KEY is unset or empty — common in CI, fresh shells, cron jobs, or containers where the env var wasn't passed through (-e/--env-file omitted).

Common situations: Env var set in the interactive shell but not in docker run/systemd/cron; key stored in .env which isn't loaded by the process; typo in variable name (OPENAI_API_KEY vs OPENAI_APIKEY); CI secrets not configured on the fork PR.

Related errors

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