mastra-ai/mastra · error

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

Error message

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

What it means

createStep only accepts plain StepParams, an Agent instance, a ToolStep, or a Processor. Anything else (plain functions, tool definitions not wrapped as ToolStep, strings, undefined from bad imports) falls through all instanceof/shape checks and reaches this final throw. It is a guard against passing unsupported step inputs to workflow.createStep.

Source

Thrown at packages/core/src/workflows/workflow.ts:453

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

  // StepParams check must come before isProcessor since both have 'id'
  // StepParams always has 'execute', while Processor has processor methods
  if (isStepParams(params)) {
    return createStepFromParams(params);
  }

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

  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,
>(
  params: StepParams<TStepId, TStateSchema, TInputSchema, TOutputSchema, TResumeSchema, TSuspendSchema>,
): Step<
  TStepId,
  TStateSchema extends PublicSchema<any> ? InferPublicSchema<TStateSchema> : unknown,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the value passed is one of: StepParams object, Agent instance, ToolStep, or Processor.
2. If passing a tool, wrap it as a ToolStep (e.g. via createTool from the right package).
3. Log the value and its constructor before createStep to spot undefined/mistyped inputs.
4. Fix broken imports (check for circular deps returning undefined).
5. Update to matching @mastra/core versions across packages so instanceof checks pass.

Example fix

// before
workflow.createStep(myTool);
// after
import { createTool } from '@mastra/core/tools';
const toolStep = createTool({ id: 'myTool', ... });
workflow.createStep(toolStep);

if (params == null) throw new TypeError('createStep received undefined — check imports');
const ok = typeof params === 'object' && ('execute' in (params as object) || params instanceof Agent || params instanceof Processor);

function isStepParams(v: unknown): v is StepParams {
  return typeof v === 'object' && v !== null && 'execute' in v && typeof (v as StepParams).execute === 'function';
}

try {
  workflow.createStep(candidate as StepParams);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid input: expected StepParams')) {
    console.error('Bad step input:', candidate?.constructor?.name);
  } else throw e;
}

When it happens

Trigger: Passing a raw tool object instead of a ToolStep; passing a function; passing undefined/null due to a failed import or circular dependency; passing a Processor created elsewhere but mutated; passing an object that almost matches StepParams but with misspelled keys like 'executes' instead of 'execute'.

Common situations: Migrating between Mastra versions where step param shapes changed; forgetting to wrap an AI SDK tool; typos in imports causing undefined values; trying to reuse an agent created with a different base class.

Related errors

• @mastra/livekit: `workflowInput` is required when `workflow`
• save-workflow requires a Mastra context.
• InProcessStrategy: could not resolve step "${params.stepId}"
• Workflow "${params.id}" declares an array of schedules but o
• Workflow "${params.id}" declares duplicate schedule id "${en

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