Resolving ESHOPMAN Backend Startup Freezes with the Redis Event Bus Module (v2.17.0+)

Understanding ESHOPMAN Backend Startup Issues with Redis Event Bus

As experts in ESHOPMAN migrations and development, we've identified a critical issue affecting the ESHOPMAN backend startup for users leveraging the Redis Event Bus module, particularly in versions 2.17.0 and newer. This insight provides a deep dive into the problem, its root cause, and potential solutions for ESHOPMAN developers and merchants.

The Problem: ESHOPMAN Server Hangs at "Creating server"

Since ESHOPMAN v2.17.0, enabling the Redis Event Bus module causes the ESHOPMAN server to hang indefinitely at the Creating server stage during boot-up. This affects both worker and shared worker modes. The server process becomes unresponsive, consuming CPU without logging errors, never reaching the expected Server is ready status.

Disabling the Redis Event Bus module in your eshopman-config.ts allows the server to boot normally, confirming its direct involvement.

How to Reproduce the Issue

This bug is reproducible on a fresh ESHOPMAN installation using the official boilerplate:

1. Initialize a new ESHOPMAN project: npx create-eshopman-app.
2. Add the Redis Event Bus module configuration to your eshopman-config.ts:

   {
     resolve: '@eshopman/event-bus-redis',
     options: {
       redisUrl: process.env.REDIS_URL,
     },
   },

3. Set MEDUSA_WORKER_MODE to shared or worker and provide a valid REDIS_URL.
4. Start your ESHOPMAN server: eshopman develop.

The boot process will stop at:

- Creating server

and the server will not proceed.

The Technical Root Cause

Our analysis points to a significant change in ESHOPMAN v2.17.0 regarding application startup hooks. A core platform update now requires all onApplicationStart hooks to fully resolve before the ESHOPMAN application startup can complete.

The Redis Event Bus module, utilizing BullMQ for its worker, includes a startup hook that calls bullWorker.run(). BullMQ's Worker.run() is a long-running process designed to resolve only when the worker is explicitly stopped. Previously, this hook was non-blocking. With v2.17.0, ESHOPMAN now waits for this promise to resolve. Since it never resolves while active, the ESHOPMAN backend startup becomes stuck indefinitely.

This issue is not due to a BullMQ version upgrade; both ESHOPMAN v2.16.0 and v2.17.0 typically use the same BullMQ version.

Proposed Workaround and Solution

For immediate relief, temporarily remove the Redis Event Bus module from your eshopman-config.ts. For a permanent solution, the module's startup logic needs modification. Instead of awaiting the full lifecycle of bullWorker.run(), the worker should be started in a non-blocking manner. Awaiting worker.waitUntilReady() could be an alternative, allowing the startup hook to resolve once the worker is initialized and ready, without blocking the entire ESHOPMAN application startup.

This adjustment ensures the ESHOPMAN platform can complete its initialization while the Redis Event Bus worker operates in the background, crucial for a robust headless commerce backend.

Environment Details

• ESHOPMAN Version: 2.17.0
• Node.js Version: v24.11.1 (also reproduced on v20)
• Operating System: macOS (darwin)
• Package Manager: pnpm 10.x
• Worker Mode: shared / worker

We encourage ESHOPMAN developers encountering this issue to implement the proposed workaround or look for official updates addressing this behavior. Staying informed about such technical nuances ensures your ESHOPMAN-powered storefronts, managed seamlessly through HubSpot CMS and utilizing the Admin and Store APIs, remain performant and reliable.