medusajs/medusa · error · Error

Unable to retrieve the payment provider with id: ${providerI

Error message

Unable to retrieve the payment 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 payment module cannot resolve a payment provider from the container while retrieving it by id (providerId). This almost always wraps an AwilixResolutionError, meaning the provider service is not registered in the dependency container or is not declared in the project's payment provider configuration.

Source

Thrown at packages/modules/payment/src/services/payment-provider.ts:71

    super(container)
    this.#logger = container["logger"]
      ? container.logger
      : (console as unknown as Logger)
  }

  retrieveProvider(providerId: string): IPaymentProvider {
    try {
      return this.__container__[providerId] as IPaymentProvider
    } catch (err) {
      if (err.name === "AwilixResolutionError") {
        const errMessage = `
Unable to retrieve the payment 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 payment provider with id: ${providerId}, the following error occurred: ${err.message}`
      this.#logger.error(errMessage)

      throw new Error(errMessage)
    }
  }

  async createSession(
    providerId: string,
    sessionInput: InitiatePaymentInput
  ): Promise<InitiatePaymentOutput> {
    const provider = this.retrieveProvider(providerId)

    return await provider.initiatePayment(sessionInput)
  }

View on GitHub (pinned to 5e06e544a2)

Solutions

Verify the provider id passed matches exactly what is configured (e.g. 'stripe') and what the provider declares
Add the provider to the payment provider configuration in medusa-config.js (plugins or providers array)
Ensure the provider package is installed and resolves correctly (rebuild plugins if local: yarn build)
Check the logged AwilixResolutionError above this message for the true resolution cause

Example fix

// before
module.exports = defineConfig({ payment_providers: [] })
await paymentModuleService.createSession('stripe', input)

// after
module.exports = defineConfig({
  payment_providers: [
    resolveTo('@medusajs/medusa-payment-stripe'),
  ],
})
await paymentModuleService.createSession('stripe', input)

Defensive patterns

Strategy: validation

Validate before calling

const registered = new Set(['stripe', 'manual', /* from config */])
if (!registered.has(providerId)) {
  throw new Error(`Provider ${providerId} is not configured`)
}
await paymentService.createSession(providerId, input)

Type guard

const isConfiguredProvider = (id: string, configured: string[]): id is string =>
  configured.includes(id)

Try / catch

try {
  await paymentService.createSession(providerId, input)
} catch (e) {
  if (e instanceof Error && /Unable to retrieve the payment provider/.test(e.message)) {
    // config problem: surface a setup error, do not retry
  }
  throw e
}

Prevention

Keep a single source-of-truth list of configured provider ids shared by config and runtime checks
Validate provider ids at API boundary before reaching the payment module
Log the underlying AwilixResolutionError for fast diagnosis

When it happens

Trigger: Calling payment module methods that need a provider (createSession, authorizePayment, etc.) with a provider id that is not registered in medusa-config.js payment providers array, or when the provider plugin failed to load/resolve via Awilix resolution by name `pp_<providerId>`.

Common situations: Misspelled provider id, forgetting to add a custom/local plugin to payment_providers config, plugin not installed, env vars missing causing plugin resolution failure, or running with stale build after adding a new provider.

Related errors

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