{"record":{"id":"1d0b4795e9710759","repo":"mastra-ai/mastra","slug":"notification-inbox-requires-a-threadid","errorCode":null,"errorMessage":"notification-inbox requires a threadId","messagePattern":"notification-inbox requires a threadId","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/notifications/tool.ts","lineNumber":99,"sourceCode":"\n  const message =\n    delivered > 0\n      ? `${delivered} notification${delivered === 1 ? '' : 's'} will now be delivered.`\n      : 'No unread notifications needed delivery.';\n\n  return { message, delivered, markedSeen, unavailable, alreadyRead };\n}\n\nexport function createNotificationInboxTool({ storage }: { storage: NotificationsStorage }) {\n  return createTool({\n    id: 'notification-inbox',\n    description:\n      'Inspect and manage the current thread notification inbox. Use this to list pending notifications, read full details after a summary, mark notifications seen, dismiss, archive, or search old notifications.',\n    inputSchema: notificationActionSchema,\n    execute: async (input: NotificationInboxAction, context) => {\n      const threadId = input.threadId ?? context?.agent?.threadId;\n      if (!threadId) {\n        throw new Error('notification-inbox requires a threadId');\n      }\n\n      if (input.action === 'list') {\n        const listInput: ListNotificationsInput = {\n          threadId,\n          status: input.status,\n          priority: input.priority,\n          source: input.source,\n          limit: input.limit,\n        };\n        return { notifications: await storage.listNotifications(listInput) };\n      }\n\n      if (input.action === 'search') {\n        if (!input.query) throw new Error('notification-inbox search requires query');\n        return {\n          notifications: await storage.listNotifications({\n            threadId,","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/notifications/tool.ts#L81-L117","documentation":"The notification-inbox tool needs a threadId to scope which inbox to read. It resolves threadId from the tool input or falls back to context?.agent?.threadId; if both are absent it throws. Thread scoping is mandatory because notifications are stored per-thread.","triggerScenarios":"Invoking the notification-inbox tool from an agent run with no active thread (no memory thread started), or calling the tool's execute directly without input.threadId and no agent context.","commonSituations":"Agents configured without memory/threading so context.agent.threadId is undefined; programmatic tool invocation in tests without supplying threadId; running the tool in a workflow step where no agent thread exists.","solutions":["Pass threadId explicitly in the tool input: { action: 'list', threadId: 'your-thread-id' }","Ensure the agent run has an active thread (e.g. pass a threadId/resourceId in the agent generate/stream options)","When calling execute directly (tests), provide a context object with agent.threadId set"],"exampleFix":"// before\nconst result = await inboxTool.execute({ action: 'list' });\n// after\nconst result = await inboxTool.execute({ action: 'list', threadId: 'thread-42' });","handlingStrategy":"validation","validationCode":"const resolvedThreadId = input.threadId ?? context?.agent?.threadId;\nif (!resolvedThreadId) throw new Error('Provide threadId or run the agent within a memory thread');","typeGuard":"function hasThreadId(i: { threadId?: string }, ctx?: { agent?: { threadId?: string } }): i is { threadId: string } & typeof i {\n  return typeof (i.threadId ?? ctx?.agent?.threadId) === 'string';\n}","tryCatchPattern":"try {\n  const res = await inboxTool.execute(input, context);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('requires a threadId')) {\n    return { error: 'Start a conversation thread before using the notification inbox' };\n  }\n  throw e;\n}","preventionTips":["Configure agent memory so every run has an active thread","Always pass threadId explicitly in programmatic tool calls","Validate threadId in client code before invoking the tool"],"tags":["notifications","tool","missing-argument"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}