{"record":{"id":"b7ed2afab1fa9f45","repo":"headroomlabs-ai/headroom","slug":"api-key-is-required-for-cloud-mode","errorCode":null,"errorMessage":"api_key is required for cloud mode","messagePattern":"api_key is required for cloud mode","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/memory/backends/mem0.py","lineNumber":132,"sourceCode":"        \"\"\"Ensure Mem0 client is initialized.\n\n        Returns:\n            The initialized Mem0 Memory client.\n\n        Raises:\n            ImportError: If mem0 package is not installed.\n        \"\"\"\n        if self._client is None:\n            try:\n                from mem0 import Memory as Mem0Memory\n            except ImportError:\n                raise ImportError(\n                    \"mem0 package not installed. Install with: pip install 'headroom-ai[memory-stack]'\"\n                ) from None\n\n            if self._config.mode == \"cloud\":\n                if not self._config.api_key:\n                    raise ValueError(\"api_key is required for cloud mode\")\n                # Cloud mode - use API key\n                self._client = await asyncio.to_thread(Mem0Memory, api_key=self._config.api_key)\n            else:\n                # Local mode with configuration\n                qdrant_provider_cfg: dict[str, Any] = {\n                    \"collection_name\": self._config.collection_name,\n                }\n                if self._config.qdrant_url:\n                    qdrant_provider_cfg[\"url\"] = self._config.qdrant_url\n                else:\n                    qdrant_provider_cfg[\"host\"] = self._config.qdrant_host\n                    qdrant_provider_cfg[\"port\"] = self._config.qdrant_port\n                if self._config.qdrant_api_key:\n                    qdrant_provider_cfg[\"api_key\"] = self._config.qdrant_api_key\n\n                config: dict[str, Any] = {\n                    \"vector_store\": {\n                        \"provider\": \"qdrant\",","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/backends/mem0.py#L114-L150","documentation":"ValueError raised by Mem0Backend._ensure_client() when config.mode == 'cloud' but config.api_key is falsy. Cloud mode talks to the hosted mem0 API, which authenticates exclusively via API key, so the client refuses to construct without one.","triggerScenarios":"Mem0Config(mode='cloud') with api_key omitted, None, or empty string, followed by any memory operation that triggers lazy client init.","commonSituations":"api_key read from an env var that is unset in the deployment environment; copying a local-mode config and only switching mode to 'cloud'; typos in the env var name or forgetting to load .env in the process.","solutions":["Set the api_key: Mem0Config(mode='cloud', api_key=os.environ['MEM0_API_KEY'])","Or export MEM0_API_KEY in the environment / .env and load it before constructing the config","If you meant to run self-hosted, use mode='local' with Qdrant settings instead","Check for whitespace-only or empty-string values — the guard rejects any falsy key"],"exampleFix":"# before\ncfg = Mem0Config(mode='cloud')  # no api_key\nawait backend.save('x')  # ValueError: api_key is required for cloud mode\n\n# after\nimport os\napi_key = os.environ['MEM0_API_KEY']\ncfg = Mem0Config(mode='cloud', api_key=api_key)","handlingStrategy":"validation","validationCode":"import os\n\napi_key = os.environ.get('MEM0_API_KEY')\nif not api_key:\n    raise SystemExit('MEM0_API_KEY must be set for cloud mode')\ncfg = Mem0Config(mode='cloud', api_key=api_key)","typeGuard":null,"tryCatchPattern":"try:\n    backend = Mem0Backend(Mem0Config(mode='cloud', api_key=api_key))\n    await backend.save('x')\nexcept ValueError as e:\n    if 'api_key is required' in str(e):\n        logger.error('MEM0_API_KEY missing in this environment')\n    raise","preventionTips":["Fail fast on missing env vars at process start rather than at first memory call","Include required secret names in deployment checklists / compose env sections","Distinguish local vs cloud mode explicitly per environment in config"],"tags":["python","mem0","config","api-key","authentication","validation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}