4.8.8. Retry Failed Steps

In this chapter, you’ll learn how to configure steps to allow retrial on failure.

Configure a Step’s Retrial#

By default, when an error occurs in a step, the step and the workflow fail, and the execution stops.

You can configure the step to retry on failure. The createStep function can accept a configuration object instead of the step’s name as a first parameter.

For example:

src/workflows/hello-world.ts
Show Imports
5} from "@medusajs/framework/workflows-sdk"6
7const step1 = createStep(8  {9    name: "step-1",10    maxRetries: 2,11  },12  async () => {13    console.log("Executing step 1")14
15    throw new Error("Oops! Something happened.")16  }17)18
19const myWorkflow = createWorkflow(20  "hello-world", 21  function () {22  const str1 = step1()23
24  return new WorkflowResponse({25    message: str1,26  })27})28
29export default myWorkflow

The step’s configuration object accepts a maxRetries property, which is a number indicating the number of times a step can be retried when it fails.

When you execute the above workflow, you’ll see the following result in the terminal:

Terminal
❯Executing step 1❯Executing step 1❯Executing step 1❯error:   Oops! Something happened.❯Error: Oops! Something happened.

The first line indicates the first time the step was executed, and the next two lines indicate the times the step was retried. After that, the step and workflow fail.

Step Retry Intervals#

By default, a step is retried immediately after it fails. To specify a wait time before a step is retried, pass a retryInterval property to the step's configuration object. Its value is a number of seconds to wait before retrying the step.

For example:

src/workflows/hello-world.ts
1const step1 = createStep(2  {3    name: "step-1",4    maxRetries: 2,5    retryInterval: 2, // 2 seconds6  },7  async () => {8    // ...9  }10)

Interval Changes Workflow to Long-Running#

By setting retryInterval on a step, a workflow becomes a long-running workflow that runs asynchronously in the background. So, you won't receive its result or errors immediately when you execute the workflow.

Instead, you must subscribe to the workflow's execution using the Workflow Engine Module Service. Learn more about it in this chapter.