{"record":{"id":"97eebcf8abbab555","repo":"headroomlabs-ai/headroom","slug":"openai-api-key-is-required-when-using-openai-embed","errorCode":null,"errorMessage":"openai_api_key is required when using OpenAI embedder backend","messagePattern":"openai_api_key is required when using OpenAI embedder backend","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/memory/config.py","lineNumber":154,"sourceCode":"        if self.vector_dimension < 1:\n            raise ValueError(f\"vector_dimension must be positive, got {self.vector_dimension}\")\n\n        if self.hnsw_ef_construction < 1:\n            raise ValueError(\n                f\"hnsw_ef_construction must be positive, got {self.hnsw_ef_construction}\"\n            )\n\n        if self.hnsw_m < 1:\n            raise ValueError(f\"hnsw_m must be positive, got {self.hnsw_m}\")\n\n        if self.hnsw_ef_search < 1:\n            raise ValueError(f\"hnsw_ef_search must be positive, got {self.hnsw_ef_search}\")\n\n        if self.cache_max_size < 1:\n            raise ValueError(f\"cache_max_size must be positive, got {self.cache_max_size}\")\n\n        if self.embedder_backend == EmbedderBackend.OPENAI and not self.openai_api_key:\n            raise ValueError(\"openai_api_key is required when using OpenAI embedder backend\")\n\n        # Ensure db_path is a Path object\n        if isinstance(self.db_path, str):\n            self.db_path = Path(self.db_path)\n","sourceCodeStart":136,"sourceCodeEnd":159,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/config.py#L136-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide the key: MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=os.environ['OPENAI_API_KEY'])","Or export OPENAI_API_KEY in the runtime environment of the process","If you want offline/no-API-key operation, switch to a local embedder backend (EmbedderBackend.LOCAL or equivalent)"],"exampleFix":"# before\ncfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI)\n# ValueError: openai_api_key is required when using OpenAI embedder backend\n\n# after\nimport os\ncfg = MemoryConfig(\n    embedder_backend=EmbedderBackend.OPENAI,\n    openai_api_key=os.environ['OPENAI_API_KEY'],\n)","handlingStrategy":"validation","validationCode":"import os\n\napi_key = os.environ.get('OPENAI_API_KEY')\nif not api_key:\n    raise SystemExit('OPENAI_API_KEY required for the OpenAI embedder backend')\ncfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=api_key)","typeGuard":null,"tryCatchPattern":"try:\n    cfg = MemoryConfig(embedder_backend=EmbedderBackend.OPENAI, openai_api_key=key)\nexcept ValueError as e:\n    if 'openai_api_key is required' in str(e):\n        cfg = MemoryConfig(embedder_backend=EmbedderBackend.LOCAL)  # offline fallback\n    else:\n        raise","preventionTips":["Check required env vars at process start, not lazily","Pass the key explicitly into MemoryConfig rather than relying on implicit discovery","Default to a local embedder in environments without API access"],"tags":["python","config","openai","api-key","embeddings","validation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}