ESHOPMAN Setup Crash Fix: 'api_key Service Not Found' Error Resolution

Troubleshooting ESHOPMAN Initial Setup: Resolving the "api_key Service Not Found" Error

Setting up a new ESHOPMAN instance is an exciting step towards building your headless commerce storefront on HubSpot CMS. However, some developers might encounter a specific error during the initial setup process, leading to a server crash. This community insight addresses a common issue where the ESHOPMAN server fails to start on a fresh installation, reporting that the "api_key" service cannot be found.

The Challenge: A Fresh ESHOPMAN Install Crashes

Developers using the ESHOPMAN project initialization tool for a new setup might see their server crash immediately after running migrations and attempting to start the development server. The error message typically looks like this:

error:   Service with alias "api_key" was not found.
  at create-defaults -> use-query-graph-step (invoke)

This error indicates that during the crucial create-defaults workflow – which is responsible for seeding essential default data required for your ESHOPMAN instance – the system attempts to query a service alias named "api_key" that isn't available in the application container.

Understanding the Root Cause

The core of this issue lies within ESHOPMAN's modular architecture, built on Node.js/TypeScript. ESHOPMAN modules are defined with specific properties, including whether they should be auto-loaded into the application's service container. For the api_key module, its definition explicitly sets defaultPackage: false. This configuration prevents the module from being automatically loaded at startup, even though the create-defaults workflow – a critical part of a fresh installation's initialization – depends on it to function correctly.

Existing ESHOPMAN stores that were set up on earlier versions typically do not encounter this problem because their default data was properly seeded before this particular configuration detail was introduced or changed.

How to Reproduce (and Confirm) the Issue

You might encounter this if you follow these steps for a fresh ESHOPMAN project:

Initialize a new ESHOPMAN project using the ESHOPMAN CLI.
Configure your DATABASE_URL in your .env file to point to a fresh PostgreSQL database.
Run database migrations (e.g., npx eshopman db:migrate).
Attempt to start the ESHOPMAN server (e.g., npx eshopman develop).

The server will likely crash with the "Service with alias 'api_key' was not found" error.

The Workaround: Manually Loading the api_key Module

While the ESHOPMAN team works on a permanent solution, a straightforward workaround involves explicitly adding the api_key module to your ESHOPMAN configuration. You'll need to modify your eshopman-config.ts file (or equivalent configuration file in your project) to include the api_key module in the modules array:

// In your eshopman-config.ts
modules: [
  { key: "api_key", resolve: "@eshopman/core/api-key" }, // Adjust path if necessary
  // ... other modules
]

Important Note: While this specific workaround addresses the api_key module, it's possible that other default modules might also be affected by similar auto-loading issues in specific ESHOPMAN versions. If you encounter further "Service not found" errors after applying this fix, you may need to investigate and manually add those missing modules to your configuration as well.

Moving Forward with ESHOPMAN

This insight highlights a specific challenge during initial setup and provides an immediate solution for ESHOPMAN developers. By understanding the modular architecture and how modules are loaded, you can efficiently troubleshoot and get your ESHOPMAN headless commerce backend up and running, ready to power your HubSpot CMS storefront. The ESHOPMAN community is a great resource for sharing such knowledge and best practices.

Troubleshooting ESHOPMAN Initial Setup: Resolving the 'api_key Service Not Found' Error