mastra-ai/mastra · error · HTTPException

messageIds is required

Error message

messageIds is required

What it means

DELETE_MESSAGES_ROUTE (POST /memory/messages/delete) requires a messageIds payload. If messageIds is undefined or null after request parsing, the handler throws HTTPException 400 'messageIds is required'. The endpoint accepts a single string, a single { id } object, or arrays of either, but not an absent value.

Source

Thrown at packages/server/src/server/handlers/memory.ts:1730

});

export const DELETE_MESSAGES_ROUTE = createRoute({
  method: 'POST',
  path: '/memory/messages/delete',
  responseType: 'json',
  queryParamSchema: deleteMessagesQuerySchema,
  bodySchema: deleteMessagesBodySchema,
  responseSchema: deleteMessagesResponseSchema,
  summary: 'Delete messages',
  description: 'Deletes specific messages from memory',
  tags: ['Memory'],
  requiresAuth: true,
  handler: async ({ mastra, agentId, resourceId, messageIds, requestContext }) => {
    try {
      const effectiveResourceId = getEffectiveResourceId(requestContext, resourceId);

      if (messageIds === undefined || messageIds === null) {
        throw new HTTPException(400, { message: 'messageIds is required' });
      }

      // Normalize messageIds to the format expected by deleteMessages
      // Convert single values to arrays and extract IDs from objects
      let normalizedIds: string[] | { id: string }[];

      if (Array.isArray(messageIds)) {
        // Already an array - keep as is (could be string[] or { id: string }[])
        normalizedIds = messageIds;
      } else if (typeof messageIds === 'string') {
        // Single string ID - wrap in array
        normalizedIds = [messageIds];
      } else {
        // Single object with id property - wrap in array
        normalizedIds = [messageIds];
      }

      // Extract string IDs for validation and deletion

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always send messageIds in the JSON body, e.g. { messageIds: ['msg-1', 'msg-2'] }.
2. Guard client-side: if the selection is empty, skip the API call instead of sending a body without messageIds.
3. Update @mastra/client-js to a version matching the server so the typed deleteMessages(messageIds) signature is enforced.
4. Send an array — single strings and { id } objects are accepted and normalized server-side.

Example fix

// before
await client.post('/memory/messages/delete', {});

// after
if (selectedIds.length > 0) {
  await client.post('/memory/messages/delete', { messageIds: selectedIds });
}

if (!messageIds || (Array.isArray(messageIds) && messageIds.length === 0)) {
  throw new Error('messageIds is required and must contain at least one id');
}

function hasMessageIds(body: unknown): body is { messageIds: string[] | { id: string }[] } {
  const ids = (body as any)?.messageIds;
  if (typeof ids === 'string') return ids.length > 0;
  return Array.isArray(ids) && ids.length > 0;
}

try {
  await client.deleteMessages(messageIds);
} catch (e) {
  if (e instanceof HTTPException && e.status === 400 && /messageIds is required/.test(e.message)) {
    console.error('Request body must include messageIds');
    return;
  }
  throw e;
}

When it happens

Trigger: POST /api/memory/messages/delete with an empty body, a JSON body without the messageIds key, or a client SDK call like deleteMessages() invoked with no arguments (e.g., spreading an empty options object where the field is dropped).

Common situations: Client code building the request body conditionally so messageIds is omitted when the selection list is empty; sending Content-Type application/json with an empty body; older client versions sending a differently named field (e.g., ids) that the server ignores.

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

• Both threadId or resourceId must be provided
• Messages are required
• conversation_id requires the target agent to have memory con
• ${errorMessage}
• Argument "${key}" is required

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