mastra-ai/mastra · error · HTTPException

agent signals are not supported by this Mastra core version

Error message

agent signals are not supported by this Mastra core version

What it means

The signal handler checks at runtime whether the resolved agent instance exposes a sendSignal method. If it does not, the installed @mastra/core version predates agent signal support, so the server responds with HTTP 501 Not Implemented instead of failing obscurely. This is a version-capability guard, not an input validation error.

Source

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

      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 { sendSignal?: unknown }).sendSignal !== 'function') {
        throw new HTTPException(501, { message: 'agent signals are not supported by this Mastra core version' });
      }

      const agentSignal = signal as AgentSignalInput;

      if (runId) {
        const result = await agent.sendSignal(agentSignal, {
          runId,
          ...(effectiveResourceId ? { resourceId: effectiveResourceId } : {}),
          ...(effectiveThreadId ? { threadId: effectiveThreadId } : {}),
          ...(ifActive ? { ifActive } : {}),
        });
        // `accepted` resolves once the runtime decides how to route the signal; it only
        // rejects on a setup/misconfig failure (e.g. no model), which `handleError` maps
        // below. `runId` is present on `wake`/`deliver` (a run exists); `persist`/`discard`
        // never start a run, so we fall back to the caller's `runId` to keep the wire
        // contract (`runId: string`) stable.
        const settled = await result.accepted;
        const settledRunId = 'runId' in settled ? settled.runId : runId;

View on GitHub (pinned to 75dd419e61)

Solutions

Upgrade @mastra/core (and matching @mastra/* packages) to a version that supports agent signals
Verify with pnpm ls @mastra/core that all workspace packages resolve the same core version
If using a custom agent implementation, add a sendSignal method compatible with the current core API

Example fix

// before (package.json)
"@mastra/core": "0.10.0"
// after
"@mastra/core": "latest",
// then: pnpm install && pnpm build

Defensive patterns

Strategy: type-guard

Validate before calling

function agentSupportsSignals(agent: unknown): boolean {
  return typeof (agent as { sendSignal?: unknown })?.sendSignal === 'function';
}

Type guard

function supportsSendSignal(a: unknown): a is { sendSignal: Function } {
  return !!a && typeof (a as { sendSignal?: unknown }).sendSignal === 'function';
}

Try / catch

try {
  await agent.sendSignal(signal, opts);
} catch (e) {
  if (e?.status === 501) throw new Error('Upgrade @mastra/core to use agent signals');
  throw e;
}

Prevention

Keep @mastra/core and @mastra/server versions aligned; check pnpm ls @mastra/core after upgrades
Detect capability once at startup (typeof agent.sendSignal === 'function') and feature-flag the UI
Read the mastra changelog before adopting new endpoints like signals

When it happens

Trigger: POSTing to the agent signal endpoint (e.g. /api/agents/:agentId/signals) when the resolved agent object lacks a callable sendSignal — i.e. an older core version or an agent wrapper that doesn't implement it.

Common situations: Mixed @mastra/* package versions after a partial upgrade (server package newer than core), a custom agent subclass overriding/omitting sendSignal, or a stub/mock agent in tests.

Related errors

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