mem0ai/mem0 · error · ValueError

Top-level entity parameters {invalid_keys} are not supported

Error message

Top-level entity parameters {invalid_keys} are not supported in {method_name}(). Use filters={'user_id': '...'} instead.

What it means

Error "Top-level entity parameters {invalid_keys} are not supported in {method_name}(). Use filters={'user_id': '...'} instead." thrown in mem0ai/mem0.

Source

Thrown at mem0/memory/main.py:169

    On the update path `existing_payload` carries the memory's current scope, so
    re-sending an identical value is silently accepted; only a changed value warns.
    On the creation path there is no prior payload, so pass an empty dict and every
    identity key present in `metadata` is dropped with a warning.
    """
    clean = {}
    for key, value in metadata.items():
        if key not in _IDENTITY_KEYS:
            clean[key] = value
        elif value != existing_payload.get(key):
            logger.warning(f"{context}: ignoring metadata['{key}'] - identity fields cannot be set through metadata")
    return clean


def _reject_top_level_entity_params(kwargs: Dict[str, Any], method_name: str) -> None:
    """Reject top-level entity parameters - must use filters instead."""
    invalid_keys = ENTITY_PARAMS & set(kwargs.keys())
    if invalid_keys:
        raise ValueError(
            f"Top-level entity parameters {invalid_keys} are not supported in {method_name}(). "
            f"Use filters={{'user_id': '...'}} instead."
        )


def _validate_and_trim_entity_id(value: Optional[Any], name: str) -> Optional[str]:
    """
    Validates and normalizes an entity ID.
    - Coerces non-string values (e.g. integer ids) to str
    - Trims leading/trailing whitespace
    - Rejects empty or whitespace-only strings
    - Rejects strings containing internal whitespace

    Args:
        value: The entity ID value to validate
        name: The parameter name (for error messages)

    Returns:

View on GitHub (pinned to 001c235229)

Solutions

1. Move entity parameters into filters, e.g. method(filters={'user_id': '...'}).

When it happens

Trigger: Thrown at mem0/memory/main.py:169 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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