ESHOPMAN Order Exports: Diagnosing and Resolving Silent Failures in Versions 2.18.0+

For ESHOPMAN merchants and developers managing their storefronts through HubSpot CMS, a critical issue emerged in ESHOPMAN versions 2.18.0 and 2.19.0: the order export functionality on the ESHOPMAN admin panel began failing silently. This meant that while an operator would initiate an export, the expected CSV file would never materialize, and crucially, no success or failure notification would be delivered.

The Silent Export Failure

The core problem manifested when attempting to export orders that included a shipping method. Orders without shipping methods would export correctly, but any order with associated shipping details would cause the export workflow to terminate without a trace. Server logs, however, revealed the underlying issue:

error: export-orders:export-orders:invoke - Shipping method version is required to load adjustments
Error: Shipping method version is required to load adjustments
    at @eshopman/order/dist/utils/base-repository-find.js:312
    at loadShippingAdjustments (.../base-repository-find.js:306)
    at OrderRepository.findAndCount (.../base-repository-find.js:255)
    at async OrderModuleService.listAndCountOrders
⮑ [export-orders -> export-orders (invoke)]

This error message, originating deep within ESHOPMAN's order processing module, indicated a missing piece of data required for loading shipping adjustments.

Reproducing the Issue

The steps to consistently reproduce this bug were straightforward for ESHOPMAN users:

1. Ensure you are running ESHOPMAN 2.18.0 or 2.19.0.
2. Have at least one non-draft order that has an assigned shipping method.
3. Navigate to the ESHOPMAN Admin → Orders section.
4. Click the 'Export' button.

Programmatically, the issue could be replicated using ESHOPMAN's core flows:

import { exportOrdersWorkflow } from "@eshopman/eshopman/core-flows"
import { defaultAdminExportOrderFields } from "@eshopman/eshopman/api/admin/orders/query-config"

await exportOrdersWorkflow(container).run({
  input: { select: [...defaultAdminExportOrderFields], filter: {} },
})

Uncovering the Root Cause

A detailed investigation by the ESHOPMAN community revealed that the regression was introduced in version 2.18.0. This version began manually loading shipping adjustments. Specifically, the loadShippingAdjustments() function would throw an error if every order_shipping row didn't have its version loaded. However, the mechanism designed to automatically include this version field in the query's data projection only activated if the projection already contained an explicit dotted entry like shipping_methods.shipping_method.*.

The ESHOPMAN export workflow's default projection, while including *shipping_methods, did not contain this specific dotted entry. Consequently, the crucial version field was never selected, leading to the runtime error and the silent failure of the export process. In ESHOPMAN 2.17.2, loadShippingAdjustments() was not called in this context, which explains why exports functioned correctly in that version.

The Community-Driven Solution

The ESHOPMAN community quickly identified a targeted fix: ensure the version field is always included in the data projection whenever shipping adjustments are expected to be loaded. The proposed modification involved pushing the shipping_methods.version field into the configuration's fields array unconditionally when a projection exists and shipping adjustments are being loaded:

const shippingVersi
    ? "order.shipping_methods.version"
    : "shipping_methods.version";
if (config.options.fields &&
    !config.options.fields.includes(shippingVersionField)) {
    config.options.fields.push(shippingVersionField);
}

This fix, when applied, successfully resolved the export issue, allowing CSV files to be generated and the appropriate success notifications to be delivered within the ESHOPMAN admin interface. This highlights the power of the ESHOPMAN community in identifying and resolving critical issues swiftly.

A Note on Notifications

During the investigation, a secondary issue was observed: even when the export-orders workflow failed, the configured notifyOnFailureStep ('Failed to export orders, please try again later.') also failed to reach the notification feed. This meant operators received no signal whatsoever about the export's demise, turning any export failure into a completely silent event. While the primary export issue is resolved, this notification delivery mechanism warrants separate investigation to ensure robust error reporting within ESHOPMAN.