{"record":{"id":"5da4e795895fa1d9","repo":"mastra-ai/mastra","slug":"gateway-memory-message-metadata-filters-are-not-su","errorCode":null,"errorMessage":"Gateway memory message metadata filters are not supported by this gateway endpoint. Remove filter.metadata or query a local memory store.","messagePattern":"Gateway memory message metadata filters are not supported by this gateway endpoint\\. Remove filter\\.metadata or query a local memory store\\.","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"warning","filePath":"packages/server/src/server/handlers/memory.ts","lineNumber":1110,"sourceCode":"    includeSystemReminders,\n    requestContext,\n  }: any) => {\n    try {\n      const effectiveThreadId = getEffectiveThreadId(requestContext, threadId);\n      const effectiveResourceId = getEffectiveResourceId(requestContext, resourceId);\n      validateBody({ threadId: effectiveThreadId });\n\n      if (!effectiveThreadId) {\n        throw new HTTPException(400, { message: 'No threadId found' });\n      }\n\n      // Gateway proxy: list messages from gateway API\n      const agent = await getAgentFromContext({ mastra, agentId, requestContext });\n      if (agent && (await isGatewayAgentAsync(agent))) {\n        const gwClient = getGatewayClient();\n        if (gwClient) {\n          if (filter?.metadata && Object.keys(filter.metadata).length > 0) {\n            throw new HTTPException(501, {\n              message:\n                'Gateway memory message metadata filters are not supported by this gateway endpoint. Remove filter.metadata or query a local memory store.',\n            });\n          }\n\n          // Validate thread ownership before returning messages\n          const threadResult = await gwClient.getThread(effectiveThreadId);\n          if (threadResult) {\n            await enforceThreadAccess({\n              mastra,\n              requestContext,\n              threadId: effectiveThreadId,\n              thread: toLocalThread(threadResult.thread),\n              effectiveResourceId,\n            });\n          }\n\n          const effectivePage = page ?? 0;","sourceCodeStart":1092,"sourceCodeEnd":1128,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/memory.ts#L1092-L1128","documentation":"When the agent is backed by a gateway (remote Mastra gateway) and a message list request includes filter.metadata, the local handler throws HTTPException(501) because the gateway listMessages endpoint does not support metadata filters. It asks callers to drop the filter or use a local memory store.","triggerScenarios":"GET messages with a non-empty filter.metadata object on a gateway-proxied agent (isGatewayAgentAsync true and a gateway client configured).","commonSituations":"Client code written against a local-memory deployment (metadata filtering supported) is reused against a gateway agent; feature flag switched an agent to gateway mode; shared UI code always sends metadata filters.","solutions":["Remove filter.metadata from the request when targeting a gateway agent, filtering results client-side instead.","Switch the agent/deployment to a local memory store if metadata filtering is required.","Feature-detect: only include filter.metadata when the agent is not gateway-backed.","Upgrade the gateway (or check for a newer endpoint) that supports metadata filters, if available."],"exampleFix":"// before\nconst res = await listMessages({ threadId, filter: { metadata: { userId } } });\n// after\nconst filter = isGatewayAgent ? undefined : { metadata: { userId } };\nconst res = await listMessages({ threadId, filter });\nconst filtered = isGatewayAgent ? res.messages.filter(m => m.metadata?.userId === userId) : res.messages;","handlingStrategy":"fallback","validationCode":"if (isGatewayAgent && filter?.metadata && Object.keys(filter.metadata).length > 0) {\n  console.warn('metadata filters unsupported on gateway; filtering client-side');\n}\nconst safeFilter = isGatewayAgent ? { ...filter, metadata: undefined } : filter;","typeGuard":"function supportsMetadataFilter(agent: Agent): boolean {\n  return !isGatewayAgent(agent);\n}","tryCatchPattern":"try {\n  return await listMessages({ threadId, filter });\n} catch (e) {\n  if (isHttpException(e, 501)) {\n    const all = await listMessages({ threadId, filter: undefined });\n    return all.filter(m => matchesMetadata(m, filter.metadata));\n  }\n  throw e;\n}","preventionTips":["Feature-detect gateway agents before sending advanced filters.","Keep client filter code behind an adapter per backend (gateway vs local).","Track gateway feature parity notes when upgrading deployments."],"tags":["http-501","gateway","unsupported-feature"],"backgroundTag":"endpoint-not-implemented","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}