Resolving 'Service Not Found' Errors in ESHOPMAN Admin API After Recent Updates

Resolving 'Service Not Found' Errors in ESHOPMAN Admin API After Recent Updates

The ESHOPMAN platform, celebrated for its robust headless commerce capabilities and seamless integration with HubSpot for storefront management, continuously evolves. However, with updates, developers occasionally encounter unexpected behaviors. A recent ESHOPMAN platform update introduced a specific challenge for developers leveraging the Admin API, particularly when constructing custom routes and plugins.

The Core Issue: 'Service with alias "undefined" was not found'

Developers working with ESHOPMAN's Node.js/TypeScript backend have reported an issue where, after a recent update to ESHOPMAN v2.13.2 (or similar versions), custom Admin API routes began throwing a Service with alias "undefined" was not found error. This error typically occurs when these routes attempt to query data using the query.graph method, which is fundamental for interacting with ESHOPMAN's data layer.

The root cause was traced to a change in how req.queryConfig is populated. Previously, spreading req.queryConfig into a query.graph call was a safe and common practice. However, the update caused req.queryConfig to sometimes include an entity field with an undefined value. When this configuration was spread into a query.graph call like this:

const { data } = await query.graph({
  entity: "some_entity",
  filters,
  ...req.queryConfig,
})

The entity: "some_entity" would be inadvertently overwritten by entity: undefined from req.queryConfig. This leads to the RemoteJoiner, a key component of ESHOPMAN's data fetching mechanism, failing to locate a service with the alias "undefined", thus triggering the error.

Understanding the Technical Impact

This behavior primarily impacts custom plugins and endpoints built on ESHOPMAN's Node.js/TypeScript framework that interact with the Admin API. It's suspected to be related to changes in Role-Based Access Control (RBAC) field filtering and the internal prepareListQuery function, which now sometimes produces a remoteQueryConfig containing an entity field, even if its value is undefined.

Immediate Workaround for Developers

While the ESHOPMAN core development team is actively working on a permanent fix, a robust workaround has been identified and shared by the community. This workaround involves defensively destructuring req.queryConfig to exclude the potentially problematic entity field before spreading the rest of the configuration into query.graph.

Here’s how to implement the workaround:

// Original problematic code:
// const { data } = await query.graph({
//   entity: "some_entity",
//   filters,
//   ...req.queryConfig,
// })

// Recommended workaround:
const { entity, ...rest } = req.queryConfig; // Destructure to exclude 'entity'
const { data } = await query.graph({
  entity: "some_entity", // Explicitly set the correct entity
  filters,
  ...rest, // Spread the rest of the query config
})

By explicitly extracting entity and then spreading ...rest, you ensure that your intended entity value is always used, preventing the undefined override.

Best Practices for ESHOPMAN Development

This incident highlights the importance of defensive programming when integrating with platform APIs, especially after updates. Always test your custom routes and plugins thoroughly after any ESHOPMAN platform update. Staying engaged with the ESHOPMAN developer community and monitoring for official announcements can also help you anticipate and address such changes promptly.

The ESHOPMAN team has acknowledged this bug and is working on a resolution, ensuring the platform remains stable and powerful for managing your headless commerce storefronts via HubSpot CMS.