{"record":{"id":"e60aa8daa508acf9","repo":"headroomlabs-ai/headroom","slug":"openai-api-key-required-provide-api-key-parameter","errorCode":null,"errorMessage":"OpenAI API key required. Provide api_key parameter or set OPENAI_API_KEY environment variable.","messagePattern":"OpenAI API key required\\. Provide api_key parameter or set OPENAI_API_KEY environment variable\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/memory/adapters/embedders.py","lineNumber":637,"sourceCode":"        max_retries: int | None = None,\n    ) -> None:\n        \"\"\"Initialize the OpenAI embedder.\n\n        Args:\n            api_key: OpenAI API key. If not provided, will use OPENAI_API_KEY\n                    environment variable.\n            model_name: Model to use. Defaults to \"text-embedding-3-small\".\n            max_retries: Maximum number of retries for transient failures.\n\n        Raises:\n            ImportError: If openai library is not installed.\n            ValueError: If no API key is provided or found in environment.\n        \"\"\"\n        self._check_dependencies()\n\n        self._api_key = api_key or os.environ.get(\"OPENAI_API_KEY\")\n        if not self._api_key:\n            raise ValueError(\n                \"OpenAI API key required. Provide api_key parameter or set \"\n                \"OPENAI_API_KEY environment variable.\"\n            )\n\n        self._model_name = model_name or self.DEFAULT_MODEL\n        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES\n        self._client = None\n\n    def _check_dependencies(self) -> None:\n        \"\"\"Check that required dependencies are installed.\"\"\"\n        try:\n            import openai  # noqa: F401\n        except ImportError as e:\n            raise ImportError(\n                \"openai is required for OpenAIEmbedder. Install it with: pip install openai\"\n            ) from e\n\n    @cached_property","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/adapters/embedders.py#L619-L655","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\nemb = OpenAIEmbedder()  # ValueError: OpenAI API key required\n\n# after\nimport os\nemb = OpenAIEmbedder(api_key=os.environ[\"OPENAI_API_KEY\"])  # var actually set in this process","handlingStrategy":"validation","validationCode":"import os\n\napi_key = os.environ.get(\"OPENAI_API_KEY\")\nif not api_key:\n    raise SystemExit(\"OPENAI_API_KEY not set in this process; export it or pass api_key=\")","typeGuard":null,"tryCatchPattern":"try:\n    emb = OpenAIEmbedder(api_key=os.environ.get(\"OPENAI_API_KEY\"))\nexcept ValueError as e:\n    if \"API key\" in str(e):\n        raise SystemExit(\"OpenAI credentials missing; configure secret and restart\") from e\n    raise","preventionTips":["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."],"tags":["configuration","auth","api-key","embeddings","memory"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}