mastra-ai/mastra · warning · HTTPException

Gateway memory message metadata filters are not supported by

Error message

Gateway memory message metadata filters are not supported by this gateway endpoint. Remove filter.metadata or query a local memory store.

What it means

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.

Source

Thrown at packages/server/src/server/handlers/memory.ts:1110

    includeSystemReminders,
    requestContext,
  }: any) => {
    try {
      const effectiveThreadId = getEffectiveThreadId(requestContext, threadId);
      const effectiveResourceId = getEffectiveResourceId(requestContext, resourceId);
      validateBody({ threadId: effectiveThreadId });

      if (!effectiveThreadId) {
        throw new HTTPException(400, { message: 'No threadId found' });
      }

      // Gateway proxy: list messages from gateway API
      const agent = await getAgentFromContext({ mastra, agentId, requestContext });
      if (agent && (await isGatewayAgentAsync(agent))) {
        const gwClient = getGatewayClient();
        if (gwClient) {
          if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
            throw new HTTPException(501, {
              message:
                'Gateway memory message metadata filters are not supported by this gateway endpoint. Remove filter.metadata or query a local memory store.',
            });
          }

          // Validate thread ownership before returning messages
          const threadResult = await gwClient.getThread(effectiveThreadId);
          if (threadResult) {
            await enforceThreadAccess({
              mastra,
              requestContext,
              threadId: effectiveThreadId,
              thread: toLocalThread(threadResult.thread),
              effectiveResourceId,
            });
          }

          const effectivePage = page ?? 0;

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const res = await listMessages({ threadId, filter: { metadata: { userId } } });
// after
const filter = isGatewayAgent ? undefined : { metadata: { userId } };
const res = await listMessages({ threadId, filter });
const filtered = isGatewayAgent ? res.messages.filter(m => m.metadata?.userId === userId) : res.messages;

Defensive patterns

Strategy: fallback

Validate before calling

if (isGatewayAgent && filter?.metadata && Object.keys(filter.metadata).length > 0) {
  console.warn('metadata filters unsupported on gateway; filtering client-side');
}
const safeFilter = isGatewayAgent ? { ...filter, metadata: undefined } : filter;

Type guard

function supportsMetadataFilter(agent: Agent): boolean {
  return !isGatewayAgent(agent);
}

Try / catch

try {
  return await listMessages({ threadId, filter });
} catch (e) {
  if (isHttpException(e, 501)) {
    const all = await listMessages({ threadId, filter: undefined });
    return all.filter(m => matchesMetadata(m, filter.metadata));
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: GET messages with a non-empty filter.metadata object on a gateway-proxied agent (isGatewayAgentAsync true and a gateway client configured).

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/5da4e795895fa1d9. Report an issue: GitHub.