mem0ai/mem0 · error · ValueError

org_id must be set for organization-level operations

Error message

org_id must be set for organization-level operations

What it means

Organization-level operations (listing projects, org metadata) need only org_id, and _prepare_org_params() raises ValueError when it is absent from the client config. This is the org-level counterpart to the org+project guard. It fires client-side before any request is sent.

Source

Thrown at mem0/client/project.py:130

        Prepare query parameters for organization-level API requests.

        Args:
            kwargs: Additional keyword arguments.

        Returns:
            Dictionary containing prepared parameters.

        Raises:
            ValueError: If org_id is not provided.
        """
        if kwargs is None:
            kwargs = {}

        # Add org_id if available
        if self.config.org_id:
            kwargs["org_id"] = self.config.org_id
        else:
            raise ValueError("org_id must be set for organization-level operations")

        return {k: v for k, v in kwargs.items() if v is not None}

    @abstractmethod
    def get(self, fields: Optional[List[str]] = None) -> Dict[str, Any]:
        """
        Get project details.

        Args:
            fields: List of fields to retrieve

        Returns:
            Dictionary containing the requested project fields.

        Raises:
            ValidationError: If the input data is invalid.
            AuthenticationError: If authentication fails.
            RateLimitError: If rate limits are exceeded.

View on GitHub (pinned to 001c235229)

Solutions

Pass org_id when constructing the client before calling org-level methods
Export MEM0_ORG_ID (or your config equivalent) in the environment running the code
Copy the org ID from the Mem0 platform URL/dashboard and wire it into config

Example fix

# before
client = MemoryClient(api_key=API_KEY)
client.projects.create(name="demo")  # ValueError

# after
client = MemoryClient(api_key=API_KEY, org_id="my-org")
client.projects.create(name="demo")

Defensive patterns

Strategy: validation

Validate before calling

if not cfg.org_id:
    raise ConfigError("org-level operations require org_id")
client = MemoryClient(api_key=API_KEY, org_id=cfg.org_id)

Type guard

def can_use_org_ops(cfg) -> bool:
    return bool(getattr(cfg, "org_id", None))

Try / catch

try:
    client.projects.list()
except ValueError as e:
    if "org_id must be set" in str(e):
        return redirect_to_org_setup()
    raise

Prevention

Fail fast at boot if org-level features are enabled but org_id is missing
Store org_id next to the API key in the same secret/config source

When it happens

Trigger: Calling org-scoped methods such as projects.list()/create() on a client instantiated without org_id (e.g. only api_key, or only project_id).

Common situations: Using a memory-only client (api_key + user_id) and then trying to enumerate projects; org_id present in one environment (dashboard scripts) but omitted in the app's config; onboarding flows that list projects before the user has chosen an org.

Related errors

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