{"record":{"id":"d4078c96fbc28f1c","repo":"mem0ai/mem0","slug":"validation-001","errorCode":"VALIDATION_001","errorMessage":"At least one of 'user_id', 'agent_id', or 'run_id' must be provided.","messagePattern":"At least one of 'user_id', 'agent_id', or 'run_id' must be provided\\.","errorType":"validation","errorClass":"Mem0ValidationError","httpStatus":null,"severity":"error","filePath":"mem0/memory/main.py","lineNumber":392,"sourceCode":"    run_id = _validate_and_trim_entity_id(run_id, \"run_id\")\n\n    if user_id:\n        base_metadata_template[\"user_id\"] = user_id\n        effective_query_filters[\"user_id\"] = user_id\n        session_ids_provided.append(\"user_id\")\n\n    if agent_id:\n        base_metadata_template[\"agent_id\"] = agent_id\n        effective_query_filters[\"agent_id\"] = agent_id\n        session_ids_provided.append(\"agent_id\")\n\n    if run_id:\n        base_metadata_template[\"run_id\"] = run_id\n        effective_query_filters[\"run_id\"] = run_id\n        session_ids_provided.append(\"run_id\")\n\n    if not session_ids_provided:\n        raise Mem0ValidationError(\n            message=\"At least one of 'user_id', 'agent_id', or 'run_id' must be provided.\",\n            error_code=\"VALIDATION_001\",\n            details={\"provided_ids\": {\"user_id\": user_id, \"agent_id\": agent_id, \"run_id\": run_id}},\n            suggestion=\"Please provide at least one identifier to scope the memory operation.\"\n        )\n\n    # ---------- optional actor filter ----------\n    resolved_actor_id = actor_id or effective_query_filters.get(\"actor_id\")\n    if resolved_actor_id:\n        effective_query_filters[\"actor_id\"] = resolved_actor_id\n\n    return base_metadata_template, effective_query_filters\n\n\ndef _escape_scope_value(val: Any) -> str:\n    \"\"\"Escape the structural delimiters of the session scope key.\"\"\"\n    return str(val).replace(\"%\", \"%25\").replace(\"&\", \"%26\").replace(\"=\", \"%3D\")\n","sourceCodeStart":374,"sourceCodeEnd":410,"githubUrl":"https://github.com/mem0ai/mem0/blob/001c235229be8795e3834520467bd0d661ed8f34/mem0/memory/main.py#L374-L410","documentation":"Raised as Mem0ValidationError (error code VALIDATION_001) by _build_filters_and_metadata when Memory.add() (and other scoped APIs) is called with none of user_id, agent_id, or run_id. Every memory in the OSS SDK must be scoped to at least one actor so that get_all/search/delete_all can filter by it; an unscoped write is always a programming error. The exception carries details showing exactly which IDs were provided (all None here) and a suggestion.","triggerScenarios":"m.add(\"user prefers dark mode\") with no user_id/agent_id/run_id keyword; IDs passed inside the metadata dict instead of as keyword arguments (metadata={'user_id': 'u1'} is ignored for scoping); a wrapper that forwards **kwargs but drops the ID arguments; user_id=None coming from an unset session variable.","commonSituations":"Integrating mem0 into a chat app where the user ID is in a session/context object that is not yet populated; porting code from the hosted MemoryClient API and assuming IDs are optional; passing identifiers in metadata and expecting them to act as filters.","solutions":["Pass at least one keyword: m.add(messages, user_id='u1') (or agent_id='run' scope IDs).","If the ID lives in metadata, move it to the keyword argument; metadata cannot substitute for the scoping parameters.","Catch mem0.memory.utils.Mem0ValidationError in wrappers to return a clean 4xx to your own callers.","Make your wrapper require the user_id parameter explicitly (mandatory argument) so it cannot be forgotten."],"exampleFix":"# before\nm.add(\"Prefers dark mode\", metadata={\"user_id\": \"alice\"})\n\n# after\nm.add(\"Prefers dark mode\", user_id=\"alice\")","handlingStrategy":"validation","validationCode":"if not any([user_id, agent_id, run_id]):\n    raise ValueError(\"user_id, agent_id, or run_id is required to store a memory\")","typeGuard":"def has_scope(user_id=None, agent_id=None, run_id=None) -> bool:\n    return any(v for v in (user_id, agent_id, run_id))","tryCatchPattern":"from mem0.memory.utils import Mem0ValidationError\ntry:\n    m.add(msg, user_id=uid)\nexcept Mem0ValidationError as e:\n    if e.error_code == \"VALIDATION_001\":\n        return {\"error\": \"missing user scope\", \"detail\": str(e)}\n    raise","preventionTips":["Make user_id (or agent_id) a required positional/keyword argument of your own save-memory function.","Never rely on metadata to carry identity — scoping params only.","Catch Mem0ValidationError in API layers and map VALIDATION_001 to an HTTP 400."],"tags":["validation","add","user-id","scoping"],"backgroundTag":null,"analyzedSha":"001c235229be8795e3834520467bd0d661ed8f34","analyzedAt":"2026-08-15T01:55:42.685Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}