{"record":{"id":"de8519198ce0b645","repo":"mastra-ai/mastra","slug":"processor-returned-external-message-list-de8519","errorCode":"PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST","errorMessage":"Processor ${processor.id} returned a MessageList instance other than the one passed in. Use the messageList argument instead.","messagePattern":"Processor (.+?) returned a MessageList instance other than the one passed in\\. Use the messageList argument instead\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/workflow.ts","lineNumber":1102,"sourceCode":"\n              // Extract messageList after null check for proper type narrowing\n              const checkedMessageList = passThrough.messageList;\n\n              // Create source checker before processing to preserve message sources\n              const idsBeforeProcessing = (messages as MastraDBMessage[]).map(m => m.id);\n              const check = checkedMessageList.makeMessageSourceChecker();\n\n              const result = await processor.processInput({\n                ...baseContext,\n                messages: messages as MastraDBMessage[],\n                messageList: checkedMessageList,\n                systemMessages: (systemMessages ?? []) as CoreMessage[],\n              });\n\n              if (result instanceof MessageList) {\n                // Validate same instance\n                if (result !== checkedMessageList) {\n                  throw new MastraError({\n                    category: ErrorCategory.USER,\n                    domain: ErrorDomain.MASTRA_WORKFLOW,\n                    id: 'PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST',\n                    text: `Processor ${processor.id} returned a MessageList instance other than the one passed in. Use the messageList argument instead.`,\n                  });\n                }\n                return {\n                  ...passThrough,\n                  messages: result.get.all.db(),\n                  systemMessages: result.getSystemMessages(),\n                };\n              } else if (Array.isArray(result)) {\n                // Processor returned an array of messages\n                ProcessorRunner.applyMessagesToMessageList(\n                  result as MastraDBMessage[],\n                  checkedMessageList,\n                  idsBeforeProcessing,\n                  check,","sourceCodeStart":1084,"sourceCodeEnd":1120,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/workflow.ts#L1084-L1120","documentation":"After the input phase runs, the library validates that if a processor returns a MessageList, it is the exact same instance that was passed in. Returning a freshly constructed MessageList is rejected because the workflow keeps a single source of truth for messages; swapping instances would lose in-flight state (spans, persistence, ids). Throw via MastraError with id PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST.","triggerScenarios":"A processInput implementation does `return new MessageList(...)` or returns a MessageList obtained from another agent/run instead of the `messageList` argument.","commonSituations":"Copying the messageList to mutate it safely; reusing a MessageList cached from a previous call; misunderstanding the API and thinking a new instance must be returned.","solutions":["Mutate the passed-in messageList (e.g. messageList.add(...)) and return it (or nothing).","If you need to modify messages, use the provided MessageList methods instead of constructing a new one.","Return non-MessageList results if the processor output isn't a message list."],"exampleFix":"// before\nprocessInput({ messageList }) {\n  const copy = new MessageList(messageList.get.all);\n  copy.add(userMsg);\n  return copy;\n}\n// after\nprocessInput({ messageList }) {\n  messageList.add(userMsg);\n  return messageList;\n}","handlingStrategy":"validation","validationCode":"const out = processor.processInput(ctx);\nif (out instanceof MessageList && out !== ctx.messageList) {\n  throw new Error('Processor must return the same messageList instance');\n}","typeGuard":"function returnsSameList(out: unknown, expected?: MessageList): boolean {\n  return !(out instanceof MessageList) || out === expected;\n}","tryCatchPattern":"try {\n  await step.run(input);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'PROCESSOR_RETURNED_EXTERNAL_MESSAGE_LIST') {\n    console.error('Processor created a new MessageList — fix it to mutate the passed instance');\n  } else throw e;\n}","preventionTips":["Always mutate the passed messageList.","Never return new MessageList(...) from processors.","Code-review processors for MessageList construction.","Return undefined when no message changes are needed."],"tags":["workflow","processor","messagelist"],"backgroundTag":"processor-returned-external-message-list","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}