{"record":{"id":"09b7ee04928cf80f","repo":"mastra-ai/mastra","slug":"agent-thread-subscriptions-are-not-supported-by-th","errorCode":null,"errorMessage":"agent thread subscriptions are not supported by this Mastra core version","messagePattern":"agent thread subscriptions 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":2204,"sourceCode":"export const SUBSCRIBE_AGENT_THREAD_ROUTE = createRoute({\n  method: 'POST',\n  path: '/agents/:agentId/threads/subscribe',\n  responseType: 'stream' as const,\n  streamFormat: 'sse' as const,\n  sseFlushOnConnect: true,\n  pathParamSchema: agentIdPathParams,\n  bodySchema: subscribeAgentThreadBodySchema,\n  responseSchema: streamResponseSchema,\n  summary: 'Subscribe to agent thread runs',\n  description: 'Subscribes to future and active stream runs for a memory thread',\n  tags: ['Agents', 'Streaming'],\n  requiresAuth: true,\n  requiresPermission: 'agents:execute',\n  handler: async ({ mastra, agentId, resourceId, threadId, abortSignal, requestContext: serverRequestContext }) => {\n    try {\n      const agent = await getAgentFromSystem({ mastra, agentId, requestContext: serverRequestContext });\n      if (typeof (agent as { subscribeToThread?: unknown }).subscribeToThread !== 'function') {\n        throw new HTTPException(501, {\n          message: 'agent thread subscriptions are not supported by this Mastra core version',\n        });\n      }\n\n      const effectiveResourceId = getEffectiveResourceId(serverRequestContext, resourceId);\n      const effectiveThreadId = getEffectiveThreadId(serverRequestContext, threadId);\n\n      if (!effectiveThreadId) {\n        throw new HTTPException(400, { message: 'threadId is required' });\n      }\n\n      if (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      }","sourceCodeStart":2186,"sourceCodeEnd":2222,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L2186-L2222","documentation":"The thread subscription handler requires the agent to implement subscribeToThread for realtime updates. If the method is absent, the installed core version doesn't support thread subscriptions and the server returns HTTP 501. This is the same version-capability pattern as signals and aborts.","triggerScenarios":"Opening a thread subscription (SSE/WS subscribe route) against an agent lacking subscribeToThread — pre-subscription @mastra/core versions.","commonSituations":"New playground/server UI subscribed to threads while core is older; partial monorepo upgrade; pinned core version in lockfile resisting the bump.","solutions":["Upgrade @mastra/core to a version with subscribeToThread support","Delete the lockfile entry / run pnpm update so core actually resolves to the new version","Verify the running server process was restarted on the upgraded build"],"exampleFix":"// before (lockfile pin)\n\"@mastra/core\": \"0.10.0\" // pinned\n// after\npnpm update @mastra/core --latest && pnpm build","handlingStrategy":"type-guard","validationCode":"function agentSupportsSubscribe(agent: unknown): boolean {\n  return typeof (agent as { subscribeToThread?: unknown })?.subscribeToThread === 'function';\n}","typeGuard":"function supportsSubscribe(a: unknown): a is { subscribeToThread: Function } {\n  return !!a && typeof (a as { subscribeToThread?: unknown }).subscribeToThread === 'function';\n}","tryCatchPattern":"try {\n  await subscribeToThread(agentId, threadId);\n} catch (e) {\n  if (e?.status === 501) fallbackToPolling();\n  else throw e;\n}","preventionTips":["Confirm @mastra/core supports subscribeToThread before building realtime UI","Align all mastra package versions; watch for stale lockfile pins","Implement a polling fallback for deployments on older core"],"tags":["http-501","version-compatibility","subscriptions","server"],"backgroundTag":"feature-not-supported-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}