medusajs/medusa · error · Error

Action "${action}" could not be found

Error message

Action "${action}" could not be found

What it means

findOrThrowStepByAction is the builder's internal lookup used by step(), appendTo(), and actionStep(). When the requested action alias is not present in the (sub)graph being built, it throws this error. It means you referenced a step name that does not exist in the current workflow definition.

Source

Thrown at packages/core/orchestration/src/transaction/orchestrator-builder.ts:342

        const found = this.findStepByAction(action, subStep as InternalStep)
        if (found) {
          return found
        }
      }
    } else if (step.next && typeof step.next === "object") {
      return this.findStepByAction(action, step.next as InternalStep)
    }

    return
  }

  protected findOrThrowStepByAction(
    action: string,
    steps: InternalStep = this.steps
  ): InternalStep {
    const step = this.findStepByAction(action, steps)
    if (!step) {
      throw new Error(`Action "${action}" could not be found`)
    }

    return step
  }

  protected findParentStepByAction(
    action: string,
    step: InternalStep = this.steps
  ): InternalStep | undefined {
    if (!step.next) {
      return
    }

    const nextSteps = Array.isArray(step.next) ? step.next : [step.next]
    for (const nextStep of nextSteps) {
      if (!nextStep) {
        continue
      }

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Check the workflow definition for the exact alias spelling (case-sensitive)
2. Ensure the referenced step was added to the same builder/subtree (e.g. via appendTo/branch) before referencing it
3. Log/inspect builder.steps (JSON.stringify the flow) to see the actual action names

Example fix

// before
const s = builder.step('createOrdder') // typo

// after
const s = builder.step('createOrder')

const hasAction = (steps, name) =>
  steps.some((s) => s.action === name || (s.next && hasAction(s.next, name)))
if (!hasAction(builder.steps, action)) {
  throw new Error(`Action ${action} not in graph`)
}

When it happens

Trigger: Calling builder.step('name') / appendTo('name') / actionStep with an alias never added via addOrMergeStep/branch, or one that exists only in a different workflow or a nested subflow you did not include. Also triggered by typos or after renaming aliases.

Common situations: Renaming a step without updating references; referencing steps of a composed workflow from the wrong builder instance; dynamic alias construction producing wrong strings.

Related errors

• Action "${actionToMove}" could not be found in the following
• Cannot merge less than two actions
• Action not found.
• Method 'clearTransactionTimeout' not implemented.
• Method 'scheduleStepTimeout' not implemented.

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/12ebdb8715dca181. Report an issue: GitHub.