{"record":{"id":"e761451fea18c86b","repo":"mastra-ai/mastra","slug":"agent-signals-are-not-supported-by-this-mastra-cor","errorCode":null,"errorMessage":"agent signals are not supported by this Mastra core version","messagePattern":"agent signals are not supported by this Mastra core version","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":1961,"sourceCode":"      const effectiveResourceId = getEffectiveResourceId(serverRequestContext, resourceId);\n      const effectiveThreadId = getEffectiveThreadId(serverRequestContext, threadId);\n      const ifIdleWithContext = {\n        ifIdle: {\n          ...(ifIdle ?? {}),\n          streamOptions: { ...(normalizedIdleStreamOptions ?? {}), requestContext: serverRequestContext } as any,\n        },\n      };\n\n      if (effectiveThreadId && effectiveResourceId) {\n        const memory = await agent.getMemory({ requestContext: serverRequestContext });\n        if (memory) {\n          const thread = await memory.getThreadById({ threadId: effectiveThreadId });\n          await validateThreadOwnership(thread, effectiveResourceId);\n        }\n      }\n\n      if (typeof (agent as { sendSignal?: unknown }).sendSignal !== 'function') {\n        throw new HTTPException(501, { message: 'agent signals are not supported by this Mastra core version' });\n      }\n\n      const agentSignal = signal as AgentSignalInput;\n\n      if (runId) {\n        const result = await agent.sendSignal(agentSignal, {\n          runId,\n          ...(effectiveResourceId ? { resourceId: effectiveResourceId } : {}),\n          ...(effectiveThreadId ? { threadId: effectiveThreadId } : {}),\n          ...(ifActive ? { ifActive } : {}),\n        });\n        // `accepted` resolves once the runtime decides how to route the signal; it only\n        // rejects on a setup/misconfig failure (e.g. no model), which `handleError` maps\n        // below. `runId` is present on `wake`/`deliver` (a run exists); `persist`/`discard`\n        // never start a run, so we fall back to the caller's `runId` to keep the wire\n        // contract (`runId: string`) stable.\n        const settled = await result.accepted;\n        const settledRunId = 'runId' in settled ? settled.runId : runId;","sourceCodeStart":1943,"sourceCodeEnd":1979,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L1943-L1979","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before (package.json)\n\"@mastra/core\": \"0.10.0\"\n// after\n\"@mastra/core\": \"latest\",\n// then: pnpm install && pnpm build","handlingStrategy":"type-guard","validationCode":"function agentSupportsSignals(agent: unknown): boolean {\n  return typeof (agent as { sendSignal?: unknown })?.sendSignal === 'function';\n}","typeGuard":"function supportsSendSignal(a: unknown): a is { sendSignal: Function } {\n  return !!a && typeof (a as { sendSignal?: unknown }).sendSignal === 'function';\n}","tryCatchPattern":"try {\n  await agent.sendSignal(signal, opts);\n} catch (e) {\n  if (e?.status === 501) throw new Error('Upgrade @mastra/core to use agent signals');\n  throw e;\n}","preventionTips":["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"],"tags":["http-501","version-compatibility","agent-signals","server"],"backgroundTag":"feature-not-supported-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}