medusajs/medusa · critical · Error

Unable to retrieve the fulfillment provider with id: ${provi

Error message

Unable to retrieve the fulfillment provider with id: ${providerId} Please make sure that the provider is registered in the container and it is configured correctly in your project configuration file.

What it means

Thrown when the FulfillmentProvider service cannot resolve the provider from the container and the underlying error is an AwilixResolutionError (registration missing). This almost always means the provider was never registered — typically because it is not declared in medusa-config.js fulfillment providers or the plugin failed to load.

Source

Thrown at packages/modules/fulfillment/src/services/fulfillment-provider.ts:73

    }
    return `${(providerClass as any).identifier}_${optionName}`
  }

  protected retrieveProviderRegistration(
    providerId: string
  ): FulfillmentTypes.IFulfillmentProvider {
    try {
      return this.__container__[`fp_${providerId}`]
    } catch (err) {
      if (err.name === "AwilixResolutionError") {
        const errMessage = `
Unable to retrieve the fulfillment provider with id: ${providerId}
Please make sure that the provider is registered in the container and it is configured correctly in your project configuration file.`

        // Log full error for debugging
        this.#logger.error(`AwilixResolutionError: ${err.message}`, err)

        throw new Error(errMessage)
      }

      const errMessage = `Unable to retrieve the fulfillment provider with id: ${providerId}, the following error occurred: ${err.message}`
      this.#logger.error(errMessage)

      throw new Error(errMessage)
    }
  }

  async listFulfillmentOptions(providerIds: string[]): Promise<any[]> {
    return await promiseAll(
      providerIds.map(async (p) => {
        const provider = this.retrieveProviderRegistration(p)
        return {
          provider_id: p,
          options: (await provider.getFulfillmentOptions()) as Record<
            string,
            unknown

View on GitHub (pinned to 5e06e544a2)

Solutions

Add the provider to `fulfillment` -> `providers` in medusa-config.js (resolve path or npm package)
Confirm the provider's identifier matches the provider_id used on shipping options
Check startup logs for plugin registration errors (e.g. missing static identifier)
Restart the server after config changes

Example fix

// before
// medusa-config.js has no fulfillment providers
// after
module.exports = defineConfig({
  fulfillment: { providers: [{ resolve: './src/modules/my-fulfillment', options: {} }] },
})

Defensive patterns

Strategy: try-catch

Validate before calling

const registered = container.getRegistrationIdentifier /* or check config */
// simpler: assert config declares the provider before use
if (!config.fulfillment?.providers?.some((p) => p.resolve.includes(providerId))) throw new Error('Provider not configured')

Try / catch

try { await service.createShippingOptions(...) } catch (e) { if (/Unable to retrieve the fulfillment provider/.test(e.message)) { /* surface config guidance to operator */ } throw e }

Prevention

Declare every custom provider in medusa-config.js before referencing it on shipping options
Run a startup smoke check that resolves each configured provider from the container

When it happens

Trigger: Configuring a fulfillment option whose provider_id points to a provider not listed in medusa-config.js `fulfillment.providers`, or a local provider file that errored during registration (e.g. missing identifier, see error 604).

Common situations: New custom provider added to src/ but not registered in config; typo in provider id; plugin load failure swallowed at startup.

Related errors

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/a188733236b25db8. Report an issue: GitHub.