medusajs/medusa · critical · MedusaError

OIDC engine requires a 'callback_url' option

Error message

OIDC engine requires a 'callback_url' option

What it means

The OIDC auth provider engine was constructed without a callback_url option. The engine needs the URL that the identity provider redirects back to after login, both to build the authorization URL and to validate the callback, so it refuses to initialize when it is missing.

Source

Thrown at packages/modules/providers/auth-oidc/src/engine/engine.ts:77

   */
  protected clientPromise_?: Promise<Client>
  protected clientExpiresAt_ = 0

  constructor(options: OidcEngineOptions, cache?: ICacheService) {
    if (!options?.issuer) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC engine requires an 'issuer' option"
      )
    }
    if (!options.client_id) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC engine requires a 'client_id' option"
      )
    }
    if (!options.callback_url) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC engine requires a 'callback_url' option"
      )
    }

    assertSecureUrl(options.issuer, "issuer")
    for (const [key, value] of [
      ["authorization_endpoint", options.authorization_endpoint],
      ["token_endpoint", options.token_endpoint],
      ["jwks_uri", options.jwks_uri],
    ] as const) {
      if (value) {
        assertSecureUrl(value, key)
      }
    }

    this.options_ = options
    this.discoveryCacheTtlMs_ =

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add callback_url to the provider options in medusa-config.js, set to your Medusa callback route (e.g. https://<host>/auth/customer/<strategy>/callback or the admin callback route).
2. If the value comes from an env var, verify it is set in .env and that the process was restarted after adding it.
3. Ensure the same URL is registered in the identity provider's allowed redirect/callback URLs.

Example fix

// before
authProviders: [
  { resolve: "@medusajs/auth-oidc", id: "google", options: { issuer: "...", client_id: "..." } },
]
// after
authProviders: [
  { resolve: "@medusajs/auth-oidc", id: "google", options: { issuer: "...", client_id: "...", callback_url: process.env.GOOGLE_CALLBACK_URL } },
]

const opts = providerConfig.options ?? {}
if (!opts.callback_url) {
  throw new Error("OIDC provider 'google' is missing options.callback_url")
}

const hasCallbackUrl = (o: Partial<OidcAuthProviderOptions>): o is OidcAuthProviderOptions =>
  typeof o.callback_url === "string" && o.callback_url.length > 0

try { new OidcEngine(options) } catch (e) { if (e instanceof MedusaError && e.type === MedusaError.Types.INVALID_DATA) { /* fail fast with config guidance */ } throw e }

When it happens

Trigger: Instantiating the OidcEngine (or the auth-oidc provider module) with an options object that omits callback_url, e.g. only passing issuer and client_id.

Common situations: medusa-config.js defines an authProvider entry for oidc but forgot the callback_url key; the value was read from an env var that is undefined in the current environment; copy-paste from another provider config that used a different key name (e.g. redirect_uri).

Related errors

• OIDC provider requires an 'issuer' option
• OIDC provider requires a 'client_id' option
• OIDC engine requires an 'issuer' option
• OIDC engine requires a 'client_id' option
• OIDC provider requires a 'callback_url' option

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