mastra-ai/mastra · error · MastraError

PROCESSOR_RETURNED_MESSAGES_AND_MESSAGE_LIST

PROCESSOR_RETURNED_MESSAGES_AND_MESSAGE_LIST

Error message

Processor ${processor.id} returned both messages and messageList. Only one of these is allowed.

What it means

Thrown when a processor's `processInputStep` returns a result object containing BOTH `messages` and `messageList`. These are alternative ways to convey the processed input, and providing both is ambiguous, so the runner rejects it with a USER-category MastraError.

Source

Thrown at packages/core/src/processors/runner.ts:2601

      }
      return {
        messageList: result,
      };
    } else if (Array.isArray(result)) {
      return {
        messages: result,
      };
    } else if (result) {
      if (result.messageList && result.messageList !== messageList) {
        throw new MastraError({
          category: 'USER',
          domain: 'AGENT',
          id: 'PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST',
          text: `Processor ${processor.id} returned a MessageList instance other than the one that was passed in as an argument. New external message list instances are not supported. Use the messageList argument instead.`,
        });
      }
      if (result.messages && result.messageList) {
        throw new MastraError({
          category: 'USER',
          domain: 'AGENT',
          id: 'PROCESSOR_RETURNED_MESSAGES_AND_MESSAGE_LIST',
          text: `Processor ${processor.id} returned both messages and messageList. Only one of these is allowed.`,
        });
      }
      const { model: _model, ...rest } = result;
      if (result.model) {
        const resolvedModel = await resolveModelConfig(result.model);
        const isSupported = isSupportedLanguageModel(resolvedModel);
        if (!isSupported) {
          throw new MastraError({
            category: 'USER',
            domain: 'AGENT',
            id: 'PROCESSOR_RETURNED_UNSUPPORTED_MODEL',
            text: `Processor ${processor.id} returned an unsupported model version ${resolvedModel.specificationVersion} in step ${stepNumber}. Only ${supportedLanguageModelSpecifications.join(', ')} models are supported in processInputStep.`,
          });
        }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Return either `messages` or `messageList`, not both — pick one representation.
2. Prefer returning the mutated `messageList` (or omit both keys if nothing changed).
3. Add a unit test asserting the processor's return shape.

Example fix

// before
return { messages, messageList };

// after
return { messageList }; // or { messages } — only one
}

const keys = ['messages', 'messageList'].filter(k => result?.[k] != null);
if (keys.length > 1) {
  throw new Error(`Processor result must set only one of: ${keys.join(', ')}`);
}

function isExclusiveResult(
  r: { messages?: unknown[]; messageList?: MessageList } | null | undefined,
): r is { messages?: unknown[]; messageList?: MessageList } {
  return !r || !(r.messages && r.messageList);
}

try {
  const res = await agent.generate(input);
} catch (e) {
  if (e instanceof MastraError && e.id === 'PROCESSOR_RETURNED_MESSAGES_AND_MESSAGE_LIST') {
    console.error('Processor returned both messages and messageList; strip one.');
  }
  throw e;
}

When it happens

Trigger: A processor returns `{ messages: [...], messageList: <instance> }` from `processInputStep` (or an input-step result object).

Common situations: Refactored processors where an old `messages` return was kept after adding `messageList`; spreading/merging result objects that accumulate both keys.

Related errors

• Aborted by processor
• EXPERIMENT_HAS_NO_TARGET
• EXPERIMENT_ALREADY_FINALIZED
• EXPERIMENT_HAS_TARGET
• INVALID_METHOD_TYPE

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