Resolving ESHOPMAN API Crashes: Understanding Workflow ID Conflicts in Custom Deployments

Understanding and Resolving ESHOPMAN Workflow ID Conflicts

The ESHOPMAN platform, built on Node.js/TypeScript, offers robust workflow management for headless commerce operations, including storefront management through HubSpot CMS. Developers often extend ESHOPMAN's core functionality with custom workflows, which can sometimes lead to unexpected issues during deployment. One such challenging problem is the 'Workflow with id "[workflow-id]" and step definition already exists' error, causing the ESHOPMAN API to crash on startup.

This insight details a specific scenario where this error occurred, even when custom code didn't directly reference the conflicting workflow ID, and provides a crucial solution for ESHOPMAN developers.

The Problem: API Crash on ESHOPMAN Start

An ESHOPMAN developer encountered an API crash during deployment with the following error message:

Error:
An error occurred while registering API Routes. Error: Workflow with id "create-fulfillment-workflow" and step definition already exists.

This occurred despite having custom workflows that wrapped ESHOPMAN core workflows, following documented best practices, and ensuring custom workflow and step IDs were unique. The issue was observed in a production-like environment (Railway Docker image with Node.js v22.11.0 and PostgreSQL 16), while local development using eshopman develop worked without issues.

Initial Troubleshooting Steps

The developer explored several avenues:

• Isolated Core Workflow Imports: Attempted to centralize imports of core ESHOPMAN workflows (e.g., from @eshopmanjs/eshopman/core-flows) into a single file to prevent multiple direct imports. This did not resolve the error.
• Dynamic Imports: Tried importing core workflows dynamically within workflow functions to defer their loading until execution. While this bypassed the build issue, it broke the runtime functionality of the workflows.
• Cache Clearing and Redeployments: Performed standard cache clearing and fresh deployments, but the error persisted.
• Version Checks: Tested with different ESHOPMAN versions (v2.12.2 and v2.13.2), with no change in behavior.

The core challenge was the ambiguity of the stack trace and the fact that the conflicting workflow ID (create-fulfillment-workflow) was not directly referenced in the custom codebase, making the root cause elusive.

The Solution: Rethinking Custom Workflow Imports

The breakthrough came from a subtle detail in how custom workflows were being imported into other parts of the application. The developer was using TypeScript path aliases (e.g., import { deleteStoreWorkflow } from "@/workflows/delete-store";) to import their own custom workflows. These custom workflows, in turn, were importing core ESHOPMAN flows.

The critical insight was that using TypeScript path aliases for custom workflow imports could, under certain build configurations or environments, lead to the core ESHOPMAN workflows being registered multiple times. This re-registration caused the 'Workflow with id already exists' error.

The fix involved changing these custom workflow imports from TypeScript path aliases to relative imports. For example, instead of:

import { deleteStoreWorkflow } from "@/workflows/delete-store";

The import was changed to a relative path, such as:

import { deleteStoreWorkflow } from "../workflows/delete-store";

This seemingly minor change resolved the build and API startup issue, allowing the ESHOPMAN API to run successfully with the custom nested workflows.

Key Takeaway for ESHOPMAN Developers

When working with custom workflows in ESHOPMAN, especially those that interact with core ESHOPMAN flows, pay close attention to how your custom workflows are imported into other modules of your application. While TypeScript path aliases offer convenience, they can sometimes lead to unexpected module resolution behaviors that cause workflows to be registered more than once, resulting in API crashes. Opting for relative imports for your custom workflows can prevent these conflicts and ensure stable ESHOPMAN API deployments, vital for managing your storefronts efficiently through HubSpot CMS.