mastra-ai/mastra · error · Error

MemoryThread.${methodName}() requires an agentId. Pass it vi

Error message

MemoryThread.${methodName}() requires an agentId. Pass it via getMemoryThread({ threadId, agentId }) or as a parameter to ${methodName}().

What it means

Thrown by MemoryThread.requireAgentId when neither the per-call agentId nor the constructor agentId is set, but a write operation needs one to resolve the request path. MemoryThread operations are agent-scoped, so the library refuses to guess which agent owns the thread.

Source

Thrown at client-sdks/client-js/src/resources/memory-thread.ts:49

    super(options);
  }

  /**
   * Builds the query string for agentId (if provided)
   */
  private getAgentIdQueryParam(prefix: '?' | '&' = '?', overrideAgentId?: string): string {
    const agentId = overrideAgentId ?? this.agentId;
    return agentId ? `${prefix}agentId=${agentId}` : '';
  }

  /**
   * Resolves the agentId to use for a write request. Prefers the per-call value, falls back
   * to the constructor value, and throws if neither is set.
   */
  private requireAgentId(perCallAgentId: string | undefined, methodName: string): string {
    const agentId = perCallAgentId ?? this.agentId;
    if (!agentId) {
      throw new Error(
        `MemoryThread.${methodName}() requires an agentId. ` +
          `Pass it via getMemoryThread({ threadId, agentId }) or as a parameter to ${methodName}().`,
      );
    }
    return agentId;
  }

  /**
   * Retrieves the memory thread details
   * @param requestContext - Optional request context to pass as query parameter
   * @returns Promise containing thread details including title and metadata
   */
  get(requestContext?: RequestContext | Record<string, any>): Promise<StorageThreadType> {
    const agentIdParam = this.getAgentIdQueryParam('?');
    const contextParam = requestContextQueryString(requestContext, agentIdParam ? '&' : '?');
    return this.request(`/memory/threads/${this.threadId}${agentIdParam}${contextParam}`);
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass agentId when fetching the thread: getMemoryThread({ threadId, agentId: 'myAgent' }).
2. Or pass agentId as a parameter to the individual MemoryThread method call.
3. Construct the MemoryThread via an Agent instance so the agentId is wired automatically.

Example fix

// before
const thread = await memory.getMemoryThread({ threadId: 't1' });
await thread.updateTitle('New title');

// after
const thread = await memory.getMemoryThread({ threadId: 't1', agentId: 'myAgent' });
await thread.updateTitle('New title');

function assertAgentId(agentId: string | undefined, op: string): asserts agentId {
  if (!agentId) throw new Error(`${op} requires an agentId`);
}
// call before any MemoryThread write
assertAgentId(threadAgentId, 'updateTitle');

function hasAgentId(t: { agentId?: string }): t is { agentId: string } {
  return typeof t.agentId === 'string' && t.agentId.length > 0;
}

try {
  await thread.updateTitle('New title');
} catch (e) {
  if (/requires an agentId/.test(e.message)) {
    await memory.getMemoryThread({ threadId, agentId: 'myAgent' }).then(t => t.updateTitle('New title'));
  } else throw e;
}

When it happens

Trigger: Calling getMemoryThread({ threadId }) without agentId, then invoking any mutating MemoryThread method (e.g. updateTitle, addMessages) without passing agentId as a parameter (client-sdks/client-js/src/resources/memory-thread.ts:49).

Common situations: Refactored code that previously fetched threads agent-less; shared helper functions that construct MemoryThread without the agent context; migrating after the API started requiring agentId per thread call.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Invalid input: expected StepParams, Agent, ToolStep, or Proc
• connect({ id, name }): "name" is required when connecting wi
• Failed to observe agent builder action stream: ${response.st
• HTTP error! status: ${response.status} - ${JSON.stringify(pa
• Unhandled content part type: ${(exhaustiveCheck as { type: s

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