{"record":{"id":"663872f855df30ad","repo":"mem0ai/mem0","slug":"top-level-entity-parameters-invalidkeys-join","errorCode":null,"errorMessage":"Top-level entity parameters [${invalidKeys.join(\", \")}] are not supported in ${methodName}(). Use filters: { user_id: \"...\" } instead.","messagePattern":"Top-level entity parameters \\[(.+?)\\] are not supported in (.+?)\\(\\)\\. Use filters: (.+?) instead\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"mem0-ts/src/client/mem0.ts","lineNumber":63,"sourceCode":"  \"userId\",\n  \"agentId\",\n  \"appId\",\n  \"runId\",\n];\n\n/**\n * Validates that no top-level entity parameters are passed.\n * @throws Error if entity params are found at top level\n */\nfunction rejectTopLevelEntityParams(\n  options: Record<string, any> | undefined,\n  methodName: string,\n): void {\n  const invalidKeys = Object.keys(options ?? {}).filter((k) =>\n    ENTITY_PARAMS.includes(k),\n  );\n  if (invalidKeys.length > 0) {\n    throw new Error(\n      `Top-level entity parameters [${invalidKeys.join(\", \")}] are not supported in ${methodName}(). ` +\n        `Use filters: { user_id: \"...\" } instead.`,\n    );\n  }\n}\n\nfunction encodePathSegment(value: unknown): string {\n  return encodeURIComponent(String(value));\n}\n\nclass APIError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"APIError\";\n  }\n}\n\ninterface ClientOptions {","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/mem0ai/mem0/blob/001c235229be8795e3834520467bd0d661ed8f34/mem0-ts/src/client/mem0.ts#L45-L81","documentation":"The hosted MemoryClient (mem0-ts/src/client/mem0.ts) has migrated entity scoping into a structured `filters` object; rejectTopLevelEntityParams() throws when legacy top-level keys (user_id, agent_id, app_id, run_id — the ENTITY_PARAMS list) appear in an options bag. It exists to break developers loudly out of the pre-v3 calling convention instead of silently ignoring scope.","triggerScenarios":"Calling client.add(messages, { user_id: 'alice' }), client.getAll({ agent_id: 'bot' }), client.search(q, { app_id: 'x' }) — any method whose options include an ENTITY_PARAMS key at the top level triggers the throw before any network call.","commonSituations":"Upgrading mem0ai npm package from a v1/v2 client to the v3 API surface; copy-pasting examples from old docs or blog posts; code generators trained on the old SDK.","solutions":["Move entity keys into filters: client.add(messages, { filters: { user_id: 'alice' } }).","Grep your codebase for `user_id:`, `agent_id:`, `app_id:`, `run_id:` inside options objects passed to MemoryClient methods and rewrite each.","Check the current TypeScript types — the options interfaces no longer declare these keys, so a typecheck usually flags them.","Pin to the old major version only as a temporary bridge while migrating."],"exampleFix":"// before\nawait client.add(messages, { user_id: \"alice\" });\n\n// after\nawait client.add(messages, { filters: { user_id: \"alice\" } });","handlingStrategy":"validation","validationCode":"const ENTITY_PARAMS = ['user_id', 'agent_id', 'app_id', 'run_id'] as const;\n\nfunction toFilters(options: Record<string, any> = {}): Record<string, any> {\n  const filters: Record<string, any> = { ...(options.filters ?? {}) };\n  for (const k of ENTITY_PARAMS) {\n    if (k in options) {\n      filters[k] = options[k];\n      delete options[k];\n    }\n  }\n  return filters;\n}\n\n// migrate call sites mechanically:\nawait client.add(messages, { filters: toFilters(options) });","typeGuard":"const hasTopLevelEntityParams = (o: Record<string, any> | undefined): boolean =>\n  Object.keys(o ?? {}).some(k => ['user_id', 'agent_id', 'app_id', 'run_id'].includes(k));","tryCatchPattern":null,"preventionTips":["Enable strict TypeScript so options bags with unknown keys are rejected at compile time.","Codemod all `user_id:`-style options into `filters:` in one pass when upgrading to the v3 client.","Prefer the SDK's exported option types over Record<string, any> at call sites."],"tags":["api-migration","validation","typescript","breaking-change"],"backgroundTag":null,"analyzedSha":"001c235229be8795e3834520467bd0d661ed8f34","analyzedAt":"2026-08-15T01:55:42.685Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}