mastra-ai/mastra · error

Thread ID is required for thread-scoped working memory updat

Error message

Thread ID is required for thread-scoped working memory updates

What it means

When working memory scope is 'thread', updates must target a specific conversation thread. The working-memory tool in listTools validates that a threadId is present in the context and throws a plain Error when it is missing, because a thread-scoped write without a thread has no destination.

Source

Thrown at packages/core/src/memory/mock.ts:263

      updateWorkingMemory: createTool({
        id: 'update-working-memory',
        description,
        inputSchema: z.object({ memory: z.string() }),
        execute: async (inputData, context) => {
          const threadId = context?.agent?.threadId;
          const resourceId = context?.agent?.resourceId;

          // Memory can be accessed via context.memory (when agent is part of Mastra instance)
          // or context.memory (when agent is standalone with memory passed directly)
          const memory = (context as any)?.memory;

          if (!memory) {
            throw new Error('Memory instance is required for working memory updates');
          }

          const scope = mergedConfig.workingMemory?.scope || 'resource';
          if (scope === 'thread' && !threadId) {
            throw new Error('Thread ID is required for thread-scoped working memory updates');
          }
          if (scope === 'resource' && !resourceId) {
            throw new Error('Resource ID is required for resource-scoped working memory updates');
          }

          if (threadId) {
            let thread = await memory.getThreadById({ threadId });

            if (!thread) {
              thread = await memory.createThread({
                threadId,
                resourceId,
                memoryConfig: _config,
              });
            }

            if (thread.resourceId && resourceId && thread.resourceId !== resourceId) {
              throw new Error(

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always supply a threadId in the memory options of the agent call: `{ memory: { thread: 'thread-123', resource: 'user-1' } }`.
2. If threads are not used, change workingMemory scope to 'resource' and ensure resourceId is provided.
3. When invoking the tool directly in tests, include threadId in the context.

Example fix

// before
await agent.generate('save my prefs', { memory: { resource: 'user-1' } }); // scope: 'thread'
// after
await agent.generate('save my prefs', {
  memory: { thread: 'thread-123', resource: 'user-1' },
});

const scope = memoryConfig?.workingMemory?.scope ?? 'resource';
if (scope === 'thread' && !threadId) throw new Error('threadId is required for thread-scoped working memory');
if (scope === 'resource' && !resourceId) throw new Error('resourceId is required for resource-scoped working memory');

function hasThreadId(ctx: unknown): ctx is { threadId: string } {
  return typeof (ctx as any)?.threadId === 'string' && (ctx as any).threadId.length > 0;
}

try {
  await agent.generate(input, memoryOpts);
} catch (e) {
  if (e instanceof Error && e.message.includes('Thread ID is required')) {
    // retry with an explicit thread id or switch workingMemory scope to 'resource'
  } else throw e;
}

When it happens

Trigger: Running an agent whose merged workingMemory config has `scope: 'thread'` while the generate/stream call (or tool invocation) lacks a threadId in the memory request context.

Common situations: Forgetting to pass `threadId` (e.g. `agent.generate(msg, { memory: { thread: '...' } })` omitted or misnamed); switching scope from default 'resource' to 'thread' without updating call sites; direct tool invocation without thread context.

Related errors

• Resource ID is required for resource-scoped working memory u
• Cannot update working memory: ${scope} ID is required
• Memory error: Resource-scoped working memory is enabled but
• Thread ID is required for recall
• MastraClient.deleteThread() requires exactly one of agentId

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