Resolving 500 Errors: ESHOPMAN Store API Product Filtering with Index Engine Enabled

A recent discussion within the ESHOPMAN community has brought to light a significant technical challenge impacting the ESHOPMAN Store API, specifically concerning product filtering. Developers and merchants utilizing ESHOPMAN 2.14.x and 2.15.x versions might encounter HTTP 500 errors when attempting to filter products by category_id or tag_id, provided the index_engine feature flag is actively enabled in their ESHOPMAN installation.

This issue directly affects the functionality of dynamic product listings on ESHOPMAN storefronts deployed via HubSpot CMS, potentially hindering customer navigation and product discovery. The error message typically observed is: Error: Could not find entity for path: product.categories. It might not be indexed. This indicates a core problem in how product data is processed and queried when the advanced indexing capabilities are engaged.

Understanding the Root Cause

The core of the problem lies in an inconsistency within the ESHOPMAN backend's request processing pipeline. When a request is made to the /store/products endpoint with filters like category_id[]=X, the system undergoes a series of transformations and checks.

An internal ESHOPMAN utility responsible for transforming product parameters, often found in a file like src/api/utils/common-validators/products/index.ts, renames the incoming category_id field. This transformation is designed to align the request parameters with the internal data model, effectively changing category_id to categories.id and then removing the original category_id key from the request data. The relevant code snippet illustrating this transformation is:

if (isPresent(data.category_id)) {
   res.categories = { id: data.category_id }
   delete res.category_id
}

However, the ESHOPMAN Store API's products route file (e.g., located at src/api/store/products/route.ts), which is intended to bypass the index engine for category and tag filters, still checks for the *original* category_id. By the time this check occurs, the category_id field has already been transformed and deleted, rendering it undefined. This leads to the bypass logic failing, causing the request to erroneously proceed through the index engine, which then cannot locate the expected entity path, resulting in the HTTP 500 error.

The critical section in the route file that causes this mismatch is:

if (FeatureFlag.isFeatureEnabled(IndexEngineFeatureFlag.key)) {
  // TODO: These filters are not supported by the index engine yet
  if (
    isPresent(filterableFields.tag_id) ||
    isPresent(filterableFields.category_id)   // ← always undefined by the time this runs
  ) {
    // ... bypass logic ...
  }
}

Impact on ESHOPMAN Developers and Merchants

This inconsistency means that ESHOPMAN storefronts, particularly those leveraging the performance benefits of the index_engine feature flag, cannot reliably filter products by categories or tags through the Store API. For developers building custom storefront experiences on HubSpot CMS, this necessitates a workaround or a fix to ensure robust product catalog functionality. It underscores the importance of careful parameter handling and feature flag interactions within the ESHOPMAN Node.js/TypeScript backend.

Understanding this root cause is a crucial step for ESHOPMAN developers to diagnose and address the issue, whether through a temporary code adjustment or by contributing to a more permanent resolution within the ESHOPMAN platform. This community insight serves as a vital piece of knowledge for maintaining high-performing and error-free ESHOPMAN storefronts.