mastra-ai/mastra · error · HTTPException

agent ${methodName} is not supported by this Mastra core ver

Error message

agent ${methodName} is not supported by this Mastra core version

What it means

The message handler resolves methodName (e.g. 'stream' or 'generate') and checks the agent instance actually has that function. If the method is missing, the installed core version doesn't support that agent messaging API and the server returns HTTP 501. Like the signal check, this is a capability/version guard.

Source

Thrown at packages/server/src/server/handlers/agents.ts:2065

  const effectiveResourceId = getEffectiveResourceId(serverRequestContext, resourceId);
  const effectiveThreadId = getEffectiveThreadId(serverRequestContext, threadId);
  const ifIdleWithContext = {
    ifIdle: {
      ...(ifIdle ?? {}),
      streamOptions: { ...(normalizedIdleStreamOptions ?? {}), requestContext: serverRequestContext } as any,
    },
  };

  if (effectiveThreadId && effectiveResourceId) {
    const memory = await agent.getMemory({ requestContext: serverRequestContext });
    if (memory) {
      const thread = await memory.getThreadById({ threadId: effectiveThreadId });
      await validateThreadOwnership(thread, effectiveResourceId);
    }
  }

  if (typeof (agent as unknown as Record<string, unknown>)[methodName] !== 'function') {
    throw new HTTPException(501, { message: `agent ${methodName} is not supported by this Mastra core version` });
  }

  if (runId) {
    const result = await agent[methodName](message, {
      runId,
      ...(effectiveResourceId ? { resourceId: effectiveResourceId } : {}),
      ...(effectiveThreadId ? { threadId: effectiveThreadId } : {}),
      ...(ifActive ? { ifActive } : {}),
    } as any);
    const settled = await result.accepted;
    const settledRunId: string = settled && 'runId' in settled ? settled.runId : runId;
    return result.signal === undefined
      ? { accepted: true as const, runId: settledRunId }
      : { accepted: true as const, runId: settledRunId, signal: result.signal };
  }

  if (!effectiveResourceId || !effectiveThreadId) {
    throw new HTTPException(400, { message: 'resourceId and threadId are required when runId is not provided' });

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Upgrade @mastra/core to a version supporting the invoked method
  2. Align all @mastra/* package versions (server must not be newer than core)
  3. Ensure the agent extends the official Agent class and doesn't delete/override the method

Example fix

// before (partial upgrade)
"@mastra/core": "^0.9.0",
"@mastra/server": "^0.10.0"
// after (aligned)
"@mastra/core": "^0.10.0",
"@mastra/server": "^0.10.0"
Defensive patterns

Strategy: type-guard

Validate before calling

function agentSupportsMethod(agent: unknown, methodName: string): boolean {
  return typeof (agent as Record<string, unknown>)?.[methodName] === 'function';
}

Type guard

function hasAgentMethod(a: unknown, m: 'stream' | 'generate'): a is Record<typeof m, Function> {
  return !!a && typeof (a as Record<string, unknown>)[m] === 'function';
}

Try / catch

try {
  await agent[methodName](message, opts);
} catch (e) {
  if (e?.status === 501) throw new Error(`Core too old for agent.${methodName}; upgrade @mastra/core`);
  throw e;
}

Prevention

When it happens

Trigger: POSTing to the agent stream/generate message endpoint on an agent whose class lacks the requested method — typically an outdated @mastra/core, or a methodName the installed core doesn't implement (e.g. newer stream APIs on old core).

Common situations: Server/frontend packages upgraded ahead of core; custom agent base classes that don't extend the official Agent; proxying a method name from a newer client to an older deployment.

Related errors

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