mem0ai/mem0 · error · ValueError

Turbopuffer API key must be provided either as a parameter o

Error message

Turbopuffer API key must be provided either as a parameter or via TURBOPUFFER_API_KEY environment variable

What it means

Raised in Turbopuffer.__init__ when neither an api_key parameter nor the TURBOPUFFER_API_KEY environment variable is present. Unlike some providers, this store has no client-injection escape hatch — a key is always required because every Turbopuffer namespace operation is authenticated.

Source

Thrown at mem0/vector_stores/turbopuffer.py:51

        batch_size: int = 100,
        extra_params: Optional[Dict[str, Any]] = None,
    ):
        """
        Initialize the Turbopuffer vector store.

        Args:
            collection_name (str): Name of the namespace/collection.
            embedding_model_dims (int): Dimensions of the embedding model.
            api_key (str, optional): API key for Turbopuffer. Defaults to None.
            region (str, optional): Turbopuffer region. Defaults to "gcp-us-central1".
            distance_metric (str, optional): Distance metric for vector similarity.
                Options: "cosine_distance" or "euclidean_squared". Defaults to "cosine_distance".
            batch_size (int, optional): Batch size for operations. Defaults to 100.
            extra_params (Dict, optional): Additional parameters for Turbopuffer client. Defaults to None.
        """
        api_key = api_key or os.environ.get("TURBOPUFFER_API_KEY")
        if not api_key:
            raise ValueError(
                "Turbopuffer API key must be provided either as a parameter or via TURBOPUFFER_API_KEY environment variable"
            )

        params = extra_params or {}
        params["region"] = region

        self.client = TurbopufferClient(api_key=api_key, **params)
        self.collection_name = collection_name
        self.embedding_model_dims = embedding_model_dims
        self.distance_metric = distance_metric
        self.batch_size = batch_size

        self.namespace = self.client.namespace(self.collection_name)

    def create_col(self, name=None, vector_size=None, distance=None):
        """
        Create a new namespace in Turbopuffer.
        Namespaces are created implicitly on first upsert, so this is a no-op.

View on GitHub (pinned to 001c235229)

Solutions

Set the env var in the running process: `export TURBOPUFFER_API_KEY=...` or load .env with python-dotenv before init.
Or pass it explicitly: `"config": {"api_key": os.environ["TURBOPUFFER_API_KEY"], ...}`.
For cloud deploys, add TURBOPUFFER_API_KEY to the service's environment/secret configuration, not just the build environment.

Example fix

# before
memory = Memory.from_config({
    "vector_store": {"provider": "turbopuffer", "config": {"collection_name": "mem"}}
})  # ValueError

# after
import os
from dotenv import load_dotenv
load_dotenv()
memory = Memory.from_config({
    "vector_store": {
        "provider": "turbopuffer",
        "config": {"collection_name": "mem", "embedding_model_dims": 1536},
    }
})

Defensive patterns

Strategy: validation

Validate before calling

import os

def turbopuffer_ready() -> bool:
    return bool(os.environ.get("TURBOPUFFER_API_KEY"))

if not turbopuffer_ready():
    raise SystemExit("TURBOPUFFER_API_KEY not set; cannot start with turbopuffer provider")

Try / catch

try:
    store = Turbopuffer(collection_name="mem", embedding_model_dims=1536)
except ValueError as e:
    if "API key" in str(e):
        raise RuntimeError("Turbopuffer credentials missing; set TURBOPUFFER_API_KEY") from e
    raise

Prevention

Note this provider has no client-injection fallback — a key is mandatory, so check it at boot.
Wire the secret from your secrets manager into env or explicit config; never assume ambient env in containers.
Add a config preflight that fails deployment, not the first request, when the key is absent.

When it happens

Trigger: Constructing Turbopuffer or Memory with provider "turbopuffer" while api_key is None and TURBOPUFFER_API_KEY is unset — e.g. the key lives in a .env file never loaded, or was added under a differently named variable in CI secrets.

Common situations: Forgetting load_dotenv() before building Memory; secret managers exporting TURBOPUFFER_KEY instead of TURBOPUFFER_API_KEY; local works but container/scheduled job fails because the env var was only set in the interactive shell.

Related errors

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/4fcc9df1dae22fd1. Report an issue: GitHub.