headroomlabs-ai/headroom · error · ValueError

api_key is required for cloud mode

Error message

api_key is required for cloud mode

What it means

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.

Source

Thrown at headroom/memory/backends/mem0.py:132

        """Ensure Mem0 client is initialized.

        Returns:
            The initialized Mem0 Memory client.

        Raises:
            ImportError: If mem0 package is not installed.
        """
        if self._client is None:
            try:
                from mem0 import Memory as Mem0Memory
            except ImportError:
                raise ImportError(
                    "mem0 package not installed. Install with: pip install 'headroom-ai[memory-stack]'"
                ) from None

            if self._config.mode == "cloud":
                if not self._config.api_key:
                    raise ValueError("api_key is required for cloud mode")
                # Cloud mode - use API key
                self._client = await asyncio.to_thread(Mem0Memory, api_key=self._config.api_key)
            else:
                # Local mode with configuration
                qdrant_provider_cfg: dict[str, Any] = {
                    "collection_name": self._config.collection_name,
                }
                if self._config.qdrant_url:
                    qdrant_provider_cfg["url"] = self._config.qdrant_url
                else:
                    qdrant_provider_cfg["host"] = self._config.qdrant_host
                    qdrant_provider_cfg["port"] = self._config.qdrant_port
                if self._config.qdrant_api_key:
                    qdrant_provider_cfg["api_key"] = self._config.qdrant_api_key

                config: dict[str, Any] = {
                    "vector_store": {
                        "provider": "qdrant",

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the api_key: Mem0Config(mode='cloud', api_key=os.environ['MEM0_API_KEY'])
2. Or export MEM0_API_KEY in the environment / .env and load it before constructing the config
3. If you meant to run self-hosted, use mode='local' with Qdrant settings instead
4. Check for whitespace-only or empty-string values — the guard rejects any falsy key

Example fix

# before
cfg = Mem0Config(mode='cloud')  # no api_key
await backend.save('x')  # ValueError: api_key is required for cloud mode

# after
import os
api_key = os.environ['MEM0_API_KEY']
cfg = Mem0Config(mode='cloud', api_key=api_key)

import os

api_key = os.environ.get('MEM0_API_KEY')
if not api_key:
    raise SystemExit('MEM0_API_KEY must be set for cloud mode')
cfg = Mem0Config(mode='cloud', api_key=api_key)

try:
    backend = Mem0Backend(Mem0Config(mode='cloud', api_key=api_key))
    await backend.save('x')
except ValueError as e:
    if 'api_key is required' in str(e):
        logger.error('MEM0_API_KEY missing in this environment')
    raise

When it happens

Trigger: Mem0Config(mode='cloud') with api_key omitted, None, or empty string, followed by any memory operation that triggers lazy client init.

Common situations: 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.

Related errors

• openai_api_key is required when using OpenAI embedder backen
• Cannot update memories belonging to other users
• default_importance must be 0.0-1.0, got {self.default_import
• dedup_similarity_threshold must be 0.0-1.0, got {self.dedup_
• vector_dimension must be positive, got {self.vector_dimensio

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