mastra-ai/mastra · error · Error

Invalid input: expected StepParams, Agent, ToolStep, or Proc

Error message

Invalid input: expected StepParams, Agent, ToolStep, or Processor

What it means

createStep() accepts four kinds of inputs: StepParams object, an Agent, a ToolStep, or a Processor. It probes each with type guards (isAgentCompatible, isToolStep, isProcessor, isStepParams) and throws this plain Error when none match, meaning the argument is not one of the supported shapes (e.g. undefined, a plain function, or a malformed object).

Source

Thrown at packages/core/src/workflows/evented/workflow.ts:361

  }

  if (isToolStep(params)) {
    return createStepFromTool(params, agentOrToolOptions);
  }

  if (isProcessor(params)) {
    const step = createStepFromProcessor(params) as ReturnType<typeof createStepFromProcessor> & {
      providesSkillDiscovery?: Processor['providesSkillDiscovery'];
    };
    step.providesSkillDiscovery = params.providesSkillDiscovery;
    return step;
  }

  if (isStepParams(params)) {
    return createStepFromParams(params);
  }

  throw new Error('Invalid input: expected StepParams, Agent, ToolStep, or Processor');
}

// ============================================
// Internal Implementations
// ============================================

function createStepFromParams<
  TStepId extends string,
  TStateSchema extends PublicSchema<any> | undefined,
  TInputSchema extends PublicSchema<any>,
  TOutputSchema extends PublicSchema<any>,
  TResumeSchema extends PublicSchema<any> | undefined = undefined,
  TSuspendSchema extends PublicSchema<any> | undefined = undefined,
  TRequestContextSchema extends PublicSchema<any> | undefined = undefined,
>(
  params: StepParams<
    TStepId,
    TStateSchema,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the value passed to createStep and confirm it is an Agent, ToolStep (tool with inputSchema/outputSchema/execute), Processor, or a StepParams object with id/inputSchema/outputSchema/execute.
2. Fix imports so the agent/tool is defined before createStep runs (watch for circular dependencies producing undefined).
3. If wrapping a custom object, convert it to a StepParams object literal with an execute function.
4. Log the argument (console.log(typeof params, params)) right before createStep to see what actually arrived.

Example fix

// before
createStep(myHandlerFunction);

// after
createStep({
  id: 'myStep',
  inputSchema: z.object({ prompt: z.string() }),
  outputSchema: z.object({ text: z.string() }),
  execute: async ({ inputData }) => ({ text: inputData.prompt }),
});

function isCreateStepInput(x: unknown): boolean {
  return !!x && typeof x === 'object' && (
    'id' in x || 'execute' in x || 'model' in x || 'processInput' in x
  );
}

const isStepCandidate = (x: unknown): x is Record<string, unknown> =>
  typeof x === 'object' && x !== null && ('id' in x || 'execute' in x);

let step;
try {
  step = createStep(candidate as any);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid input: expected StepParams')) {
    throw new Error(`createStep received invalid input: ${JSON.stringify(candidate)}`);
  }
  throw e;
}

When it happens

Trigger: Calling createStep(x) where x is undefined/null (e.g. an agent failed to import), a bare execute function instead of a params object, an object missing the identifying fields all guards check (id, execute, model, processInput, etc.), or passing a Tool whose shape differs from ToolStep.

Common situations: Circular import leaving an agent undefined at module init; passing a legacy tool or custom wrapper object not matching the expected interface; typos like createStep(executeFn); refactors after v0.x -> v1 where step definitions changed shape.

Related errors

• connect({ id, name }): "name" is required when connecting wi
• MemoryThread.${methodName}() requires an agentId. Pass it vi
• @mastra/livekit: MastraVoiceAgent requires `agent` or `gener
• @mastra/livekit: MastraVoiceAgent requires `agent` or `gener
• @mastra/livekit: `workflowInput` is required when `workflow`

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