mastra-ai/mastra · error · Error

addMessage is deprecated. Please use saveMessages instead.

Error message

addMessage is deprecated. Please use saveMessages instead.

What it means

Memory.addMessage is a permanently deprecated stub whose signature was changed to accept nothing useful, and it unconditionally throws instructing callers to use saveMessages. This forces a compile/runtime-visible break so code cannot silently use the removed write path.

Source

Thrown at packages/core/src/memory/memory.ts:604

   * @param type - The type of the message
   * @param toolNames - Optional array of tool names that were called
   * @param toolCallArgs - Optional array of tool call arguments
   * @param toolCallIds - Optional array of tool call ids
   * @returns Promise resolving to the saved message
   * @deprecated use saveMessages instead
   */
  async addMessage(_params: {
    threadId: string;
    resourceId: string;
    config?: MemoryConfigInternal;
    content: UserContent | AssistantContent;
    role: 'user' | 'assistant';
    type: 'text' | 'tool-call' | 'tool-result';
    toolNames?: string[];
    toolCallArgs?: Record<string, unknown>[];
    toolCallIds?: string[];
  }): Promise<MastraMessageV1> {
    throw new Error('addMessage is deprecated. Please use saveMessages instead.');
  }

  /**
   * Generates a unique identifier
   * @param context - Optional context information for deterministic ID generation
   * @returns A unique string ID
   */
  public generateId(context?: IdGeneratorContext): string {
    return this.#mastra?.generateId(context) || crypto.randomUUID();
  }

  /**
   * Static helper to check FGA authorization for thread access.
   * Can be called from HTTP handlers and agent execution paths.
   */
  static async checkThreadFGA(options: {
    mastra?: Mastra;
    user?: Record<string, unknown>;

View on GitHub (pinned to 75dd419e61)

Solutions

Replace addMessage calls with saveMessages({ messages: [...] }).
Convert the v1 message fields (threadId, resourceid, role, content) into the MastraMessage format saveMessages expects.
Update wrappers/utilities around Memory to batch message writes via saveMessages.

Example fix

// before
await memory.addMessage({ threadId, resourceid, content: 'hi', role: 'user', type: 'text' });

// after
await memory.saveMessages({
  messages: [{ threadId, resourceId, content: { parts: [{ type: 'text', text: 'hi' }] }, role: 'user' }],
});

Defensive patterns

Strategy: fallback

Try / catch

try {
  await (memory as any).addMessage(msg);
} catch (e) {
  if (String((e as Error).message).includes('addMessage is deprecated')) {
    await memory.saveMessages({ messages: [toMastraMessage(msg)] });
  } else throw e;
}

Prevention

Replace all addMessage call sites during upgrade; do not feature-detect around it.
Write a thin wrapper over saveMessages so message shape conversion lives in one place.
Update internal utilities/tests that reference addMessage.

When it happens

Trigger: Calling memory.addMessage(...) with the old { threadId, resourceid, content, role, type, toolNames, toolCallArgs, toolCallIds } shape anywhere in application code.

Common situations: Legacy integrations or agents built against MastraMemory v1 APIs; tutorials or internal helpers still wrapping addMessage; migration scripts that append messages one at a time.

Related errors

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