medusajs/medusa · error · Error

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

Error message

Unable to retrieve the payment provider with id: ${providerId}, the following error occurred: ${err.message}

What it means

Generic wrapper thrown when retrieving a payment provider from the container fails with an unexpected (non-Awilix-resolution) error. The underlying error message is appended, so the real cause is whatever the container or provider module threw during resolution/instantiation.

Source

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

  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)
  }

  async updateSession(
    providerId: string,
    sessionInput: UpdatePaymentInput
  ): Promise<UpdatePaymentOutput> {
    const provider = this.retrieveProvider(providerId)

View on GitHub (pinned to 5e06e544a2)

Solutions

Read the appended underlying error message — it names the actual failure
Check required env vars / API keys for the provider are set in .env
Validate the provider's options block in medusa-config.js
Reinstall or align the provider package version with your Medusa version

Example fix

// before
// .env missing key, options empty
payment_providers: [resolveTo('@medusajs/medusa-payment-stripe')]

// after
// .env: STRIPE_API_KEY=sk_test_...
payment_providers: [
  {
    resolve: '@medusajs/medusa-payment-stripe',
    options: { api_key: process.env.STRIPE_API_KEY },
  },
]

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const provider = service.retrieveProvider(id)
} catch (e) {
  const msg = e instanceof Error ? e.message : ''
  if (msg.includes('the following error occurred')) {
    // inspect appended cause; treat as environment/config failure, fail fast
  }
  throw e
}

Prevention

Set and verify all provider env vars at startup
Fail fast in dev with a health check that resolves each configured provider once at boot

When it happens

Trigger: A payment provider whose constructor or module top-level code throws (e.g. missing env var like STRIPE_API_KEY, malformed config), causing container.resolve() of `pp_<providerId>` to fail with an arbitrary exception.

Common situations: Missing API key env vars for the provider, invalid provider options in medusa-config.js, a provider package version incompatible with the installed @medusajs/* framework, or broken plugin build output.

Related errors

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