fix: prevent jobId collisions on workflow step retries by srindom · Pull Request #13786 · medusajs/medusa

srindom · 2025-10-20T19:36:10Z

Summary

What — What changes are introduced in this PR?

This PR fixes a bug where async workflow steps with retry intervals would get stuck after the first retry attempt due to Bull queue jobId collisions preventing retry jobs from executing.

Why — Why are these changes relevant or necessary?

Workflows using async steps with retry configurations (e.g., retryInterval: 1, maxRetries: 5) would fail once, schedule a retry, but the retry job would never execute, causing workflows to hang indefinitely.

How — How have these changes been implemented?

Root Cause: Bull queue was rejecting retry jobs because they had identical jobIds to the async execution jobs that already completed. Both used the format: retry:workflow:transaction:step_id:attempts.

Solution: Modified getJobId() in workflow-orchestrator-storage.ts to append a :retry suffix when interval > 0, creating unique jobIds:

Async execution (interval=0): retry:...:step_id:1
Retry scheduling (interval>0): retry:...:step_id:1:retry

Updated methods: getJobId(), scheduleRetry(), removeJob(), and clearRetry() to pass and handle the interval parameter.

Testing — How have these changes been tested, or how can the reviewer test the feature?

Added integration test retry-interval.spec.ts that verifies:

Step with retryInterval: 1 and maxRetries: 3 executes 3 times
Retry intervals are approximately 1 second between attempts
Workflow completes successfully after retries
Uses proper async workflow completion pattern with subscribe() and onFinish event

Examples

// Example workflow step that would previously get stuck
export const testRetryStep = createStep(
  {
    name: "test-retry-step",
    async: true,
    retryInterval: 1, // 1 second retry interval
    maxRetries: 3,
  },
  async (input: any) => {
    // Simulate failure on first 2 attempts
    if (attempts < 3) {
      throw new Error("Temporary failure - will retry")
    }
    return { success: true }
  }
)

// Before fix: Step would fail once, schedule retry, but retry job never fired (jobId collision)
// After fix: Step properly retries up to 3 times with 1-second intervals

Checklist

Please ensure the following before requesting a review:

I have added a changeset for this PR
- Every non-breaking change should be marked as a patch
- To add a changeset, run yarn changeset and follow the prompts
The changes are covered by relevant tests
I have verified the code works as intended locally
I have linked the related issue(s) if applicable

Additional Context

changeset-bot · 2025-10-20T19:36:14Z

🦋 Changeset detected

Latest commit: f8ce557

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 74 packages

Name	Type
@medusajs/workflow-engine-redis	Patch
@medusajs/orchestration	Patch
@medusajs/medusa	Patch
@medusajs/framework	Patch
@medusajs/modules-sdk	Patch
@medusajs/workflows-sdk	Patch
@medusajs/test-utils	Patch
@medusajs/medusa-oas-cli	Patch
integration-tests-http	Patch
@medusajs/analytics	Patch
@medusajs/api-key	Patch
@medusajs/auth	Patch
@medusajs/cache-inmemory	Patch
@medusajs/cache-redis	Patch
@medusajs/caching	Patch
@medusajs/cart	Patch
@medusajs/currency	Patch
@medusajs/customer	Patch
@medusajs/event-bus-local	Patch
@medusajs/event-bus-redis	Patch
@medusajs/file	Patch
@medusajs/fulfillment	Patch
@medusajs/index	Patch
@medusajs/inventory	Patch
@medusajs/link-modules	Patch
@medusajs/locking	Patch
@medusajs/notification	Patch
@medusajs/order	Patch
@medusajs/payment	Patch
@medusajs/pricing	Patch
@medusajs/product	Patch
@medusajs/promotion	Patch
@medusajs/region	Patch
@medusajs/sales-channel	Patch
@medusajs/settings	Patch
@medusajs/stock-location	Patch
@medusajs/store	Patch
@medusajs/tax	Patch
@medusajs/user	Patch
@medusajs/workflow-engine-inmemory	Patch
@medusajs/analytics-local	Patch
@medusajs/analytics-posthog	Patch
@medusajs/auth-emailpass	Patch
@medusajs/auth-github	Patch
@medusajs/auth-google	Patch
@medusajs/caching-redis	Patch
@medusajs/file-local	Patch
@medusajs/file-s3	Patch
@medusajs/fulfillment-manual	Patch
@medusajs/locking-postgres	Patch
@medusajs/locking-redis	Patch
@medusajs/notification-local	Patch
@medusajs/notification-sendgrid	Patch
@medusajs/payment-stripe	Patch
@medusajs/draft-order	Patch
@medusajs/core-flows	Patch
@medusajs/oas-github-ci	Patch
@medusajs/js-sdk	Patch
@medusajs/types	Patch
@medusajs/utils	Patch
@medusajs/cli	Patch
@medusajs/deps	Patch
@medusajs/telemetry	Patch
@medusajs/admin-bundler	Patch
@medusajs/admin-sdk	Patch
@medusajs/admin-shared	Patch
@medusajs/admin-vite-plugin	Patch
@medusajs/dashboard	Patch
@medusajs/icons	Patch
@medusajs/toolbox	Patch
@medusajs/ui-preset	Patch
create-medusa-app	Patch
medusa-dev-cli	Patch
@medusajs/ui	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-10-21T08:10:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

7 Skipped Deployments

Project	Deployment	Preview	Updated (UTC)
api-reference-v2	Ignored	Preview	Oct 21, 2025 10:03am
cloud-docs	Ignored	Preview	Oct 21, 2025 10:03am
docs-ui	Ignored	Preview	Oct 21, 2025 10:03am
docs-v2	Ignored	Preview	Oct 21, 2025 10:03am
medusa-docs	Ignored	Preview	Oct 21, 2025 10:03am
resources-docs	Ignored	Preview	Oct 21, 2025 10:03am
user-guide	Ignored	Preview	Oct 21, 2025 10:03am

💡 Enable Vercel Agent with $100 free credit for automated AI reviews

srindom · 2025-10-21T09:00:05Z

/snapshot-this

srindom · 2025-10-21T09:01:00Z

/snapshot-this

github-actions · 2025-10-21T09:10:32Z

🚀 A snapshot release has been made for this PR

Test the snapshots by updating your package.json with the newly published versions:

yarn add @medusajs/admin-bundler@2.11.1-snapshot-20251021090705

yarn add @medusajs/admin-sdk@2.11.1-snapshot-20251021090705

yarn add @medusajs/admin-shared@2.11.1-snapshot-20251021090705

yarn add @medusajs/admin-vite-plugin@2.11.1-snapshot-20251021090705

yarn add @medusajs/dashboard@2.11.1-snapshot-20251021090705

yarn add create-medusa-app@2.11.1-snapshot-20251021090705

yarn add @medusajs/cli@2.11.1-snapshot-20251021090705

yarn add medusa-dev-cli@2.11.1-snapshot-20251021090705

yarn add @medusajs/medusa-oas-cli@2.11.1-snapshot-20251021090705

yarn add @medusajs/core-flows@2.11.1-snapshot-20251021090705

yarn add @medusajs/framework@2.11.1-snapshot-20251021090705

yarn add @medusajs/js-sdk@2.11.1-snapshot-20251021090705

yarn add @medusajs/modules-sdk@2.11.1-snapshot-20251021090705

yarn add @medusajs/orchestration@2.11.1-snapshot-20251021090705

yarn add @medusajs/types@2.11.1-snapshot-20251021090705

yarn add @medusajs/utils@2.11.1-snapshot-20251021090705

yarn add @medusajs/workflows-sdk@2.11.1-snapshot-20251021090705

yarn add @medusajs/deps@2.11.1-snapshot-20251021090705

yarn add @medusajs/icons@2.11.1-snapshot-20251021090705

yarn add @medusajs/ui@4.0.25-snapshot-20251021090705

yarn add @medusajs/ui-preset@2.11.1-snapshot-20251021090705

yarn add @medusajs/medusa@2.11.1-snapshot-20251021090705

yarn add @medusajs/telemetry@2.11.1-snapshot-20251021090705

yarn add @medusajs/test-utils@2.11.1-snapshot-20251021090705

yarn add @medusajs/analytics@2.11.1-snapshot-20251021090705

yarn add @medusajs/api-key@2.11.1-snapshot-20251021090705

yarn add @medusajs/auth@2.11.1-snapshot-20251021090705

yarn add @medusajs/cache-inmemory@2.11.1-snapshot-20251021090705

yarn add @medusajs/cache-redis@2.11.1-snapshot-20251021090705

yarn add @medusajs/caching@2.11.1-snapshot-20251021090705

yarn add @medusajs/cart@2.11.1-snapshot-20251021090705

yarn add @medusajs/currency@2.11.1-snapshot-20251021090705

yarn add @medusajs/customer@2.11.1-snapshot-20251021090705

yarn add @medusajs/event-bus-local@2.11.1-snapshot-20251021090705

yarn add @medusajs/event-bus-redis@2.11.1-snapshot-20251021090705

yarn add @medusajs/file@2.11.1-snapshot-20251021090705

yarn add @medusajs/fulfillment@2.11.1-snapshot-20251021090705

yarn add @medusajs/index@2.11.1-snapshot-20251021090705

yarn add @medusajs/inventory@2.11.1-snapshot-20251021090705

yarn add @medusajs/link-modules@2.11.1-snapshot-20251021090705

yarn add @medusajs/locking@2.11.1-snapshot-20251021090705

yarn add @medusajs/notification@2.11.1-snapshot-20251021090705

yarn add @medusajs/order@2.11.1-snapshot-20251021090705

yarn add @medusajs/payment@2.11.1-snapshot-20251021090705

yarn add @medusajs/pricing@2.11.1-snapshot-20251021090705

yarn add @medusajs/product@2.11.1-snapshot-20251021090705

yarn add @medusajs/promotion@2.11.1-snapshot-20251021090705

yarn add @medusajs/analytics-local@2.11.1-snapshot-20251021090705

yarn add @medusajs/analytics-posthog@2.11.1-snapshot-20251021090705

yarn add @medusajs/auth-emailpass@2.11.1-snapshot-20251021090705

yarn add @medusajs/auth-github@2.11.1-snapshot-20251021090705

yarn add @medusajs/auth-google@2.11.1-snapshot-20251021090705

yarn add @medusajs/caching-redis@2.11.1-snapshot-20251021090705

yarn add @medusajs/file-local@2.11.1-snapshot-20251021090705

yarn add @medusajs/file-s3@2.11.1-snapshot-20251021090705

yarn add @medusajs/fulfillment-manual@2.11.1-snapshot-20251021090705

yarn add @medusajs/locking-postgres@2.11.1-snapshot-20251021090705

yarn add @medusajs/locking-redis@2.11.1-snapshot-20251021090705

yarn add @medusajs/notification-local@2.11.1-snapshot-20251021090705

yarn add @medusajs/notification-sendgrid@2.11.1-snapshot-20251021090705

yarn add @medusajs/payment-stripe@2.11.1-snapshot-20251021090705

yarn add @medusajs/region@2.11.1-snapshot-20251021090705

yarn add @medusajs/sales-channel@2.11.1-snapshot-20251021090705

yarn add @medusajs/settings@2.11.1-snapshot-20251021090705

yarn add @medusajs/stock-location@2.11.1-snapshot-20251021090705

yarn add @medusajs/store@2.11.1-snapshot-20251021090705

yarn add @medusajs/tax@2.11.1-snapshot-20251021090705

yarn add @medusajs/user@2.11.1-snapshot-20251021090705

yarn add @medusajs/workflow-engine-inmemory@2.11.1-snapshot-20251021090705

yarn add @medusajs/workflow-engine-redis@2.11.1-snapshot-20251021090705

yarn add @medusajs/draft-order@2.11.1-snapshot-20251021090705

Latest commit: 1d63ed8

fix: invariant for workflow step retry

ebffcbf

srindom requested a review from a team as a code owner October 20, 2025 19:36

github-actions bot added type: bug team: medusa labels Oct 20, 2025

fix: avoid job id collision

d12cd0a

retry test

5ffb1da

This comment was marked as outdated.

Sign in to view

srindom added 3 commits October 21, 2025 10:40

cleanup

430ee80

cleanup

88ead42

Merge branch 'develop' into fix/retry-workflows

50b5fea

Add changeset

cb9c8d1

srindom and others added 2 commits October 21, 2025 11:26

Merge branch 'develop' into fix/retry-workflows

aa9ccde

add test to package.json

f8ce557

carlos-r-l-rodrigues approved these changes Oct 21, 2025

View reviewed changes

adrien2p approved these changes Oct 21, 2025

View reviewed changes

srindom changed the title ~~fix: invariant for workflow step retry~~ fix: prevent jobId collisions on workflow step retries Oct 21, 2025

srindom added the automerge label Oct 21, 2025

kodiakhq bot merged commit bad0858 into develop Oct 21, 2025
30 checks passed

kodiakhq bot deleted the fix/retry-workflows branch October 21, 2025 18:27

This was referenced Oct 21, 2025

Version Packages #13800

Merged

Chore: Release psy-repos-javascript/medusa#189

Open

Chore: Release stnxo2023/medusa#125

Open

Chore: Release C-EO/medusa#30

Open

Chore: Release bhardwajRahul/medusa#71

Open

Chore: Release Klomgor/medusa#32

Open

This was referenced Oct 23, 2025

Chore: Release erickirt/medusa#11

Open

Version Packages admariner/medusa#112

Open

Version Packages #13853

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: prevent jobId collisions on workflow step retries#13786

fix: prevent jobId collisions on workflow step retries#13786
kodiakhq[bot] merged 9 commits intodevelopfrom
fix/retry-workflows

srindom commented Oct 20, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 20, 2025 •

edited

Loading

Uh oh!

vercel bot commented Oct 21, 2025 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

srindom commented Oct 21, 2025

Uh oh!

srindom commented Oct 21, 2025

Uh oh!

github-actions bot commented Oct 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

srindom commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Examples

Checklist

Additional Context

Uh oh!

changeset-bot bot commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

srindom commented Oct 21, 2025

Uh oh!

srindom commented Oct 21, 2025

Uh oh!

github-actions bot commented Oct 21, 2025

🚀 A snapshot release has been made for this PR

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

srindom commented Oct 20, 2025 •

edited

Loading

changeset-bot bot commented Oct 20, 2025 •

edited

Loading

vercel bot commented Oct 21, 2025 •

edited

Loading