mastra-ai/mastra · error · MastraError

PROCESSOR_WORKFLOW_INVALID_OUTPUT

PROCESSOR_WORKFLOW_INVALID_OUTPUT

Error message

Processor workflow ${workflow.id} returned invalid output format. Expected ProcessorStepOutput.

What it means

A workflow used as a processor must return a ProcessorStepOutput — an object with a phase field and one of messages, part, or messageList. If the workflow returns nothing meaningful the runner passes input through, but if it returns an object lacking that shape, executeWorkflowAsProcessor throws MastraError PROCESSOR_WORKFLOW_INVALID_OUTPUT to catch contract violations early.

Source

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

      throw new MastraError({
        category: 'USER',
        domain: 'AGENT',
        id: 'PROCESSOR_WORKFLOW_FAILED',
        text: `Processor workflow ${workflow.id} failed with status: ${result.status}${detailStr}`,
      });
    }

    // Extract and validate the output from the workflow result
    const output = result.result;

    if (!output || typeof output !== 'object') {
      // No output means no changes - return input unchanged
      return input;
    }

    // Validate it has the expected ProcessorStepOutput shape
    if (!('phase' in output) || !('messages' in output || 'part' in output || 'messageList' in output)) {
      throw new MastraError({
        category: 'USER',
        domain: 'AGENT',
        id: 'PROCESSOR_WORKFLOW_INVALID_OUTPUT',
        text: `Processor workflow ${workflow.id} returned invalid output format. Expected ProcessorStepOutput.`,
      });
    }

    return output as ProcessorStepOutput;
  }

  async runOutputProcessors(
    messageList: MessageList,
    observabilityContext?: ObservabilityContext,
    requestContext?: RequestContext,
    retryCount: number = 0,
    writer?: ProcessorStreamWriter,
    result?: OutputResult,
  ): Promise<MessageList> {

View on GitHub (pinned to 75dd419e61)

Solutions

Make the workflow's final step return a valid ProcessorStepOutput: { phase: ..., messages/messageList/part: ... }.
If the workflow is not meant to transform messages, don't register it as a processor — call it separately.
Check @mastra/core docs/types for ProcessorStepOutput in your version and match its shape (older versions differ).
Add a runtime check/logging on the workflow's output to confirm phase and messages fields before registering.

Example fix

// before (last step)
return { ok: true, result: cleaned };
// after
return { phase: 'output', messages: cleanedMessages };

Defensive patterns

Strategy: validation

Validate before calling

const out = getLastStepOutput(wf);
const isProcessorStepOutput = out && typeof out === 'object' && 'phase' in out && ('messages' in out || 'part' in out || 'messageList' in out);
if (!isProcessorStepOutput) throw new Error('Workflow final step must return ProcessorStepOutput');

Type guard

function isProcessorStepOutput(o) {
  return o !== null && typeof o === 'object' &&
    'phase' in o && ('messages' in o || 'part' in o || 'messageList' in o);
}

Try / catch

try {
  await runProcessors(input);
} catch (e) {
  if (e?.id === 'PROCESSOR_WORKFLOW_INVALID_OUTPUT') {
    // fix the workflow's final return value to ProcessorStepOutput shape
  } else throw e;
}

Prevention

Type workflow return values as ProcessorStepOutput at authoring time.
Don't register ordinary workflows as processors unless they return the processor contract.
Re-check output shape after @mastra/core upgrades.

When it happens

Trigger: runOutputProcessors / runInputProcessors / runProcessOutputStep / runProcessToolResult executes a workflow-as-processor whose final step returns an object without 'phase' or without any of 'messages' | 'part' | 'messageList' (e.g. it returns its own arbitrary result object).

Common situations: Reusing an ordinary business workflow as a processor without adapting its output; refactoring ProcessorStepOutput shape after a version upgrade; returning { success: true, data } style payloads from the last workflow step.

Related errors

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