medusajs/medusa · critical · MedusaError

OIDC provider requires a 'callback_url' option

Error message

OIDC provider requires a 'callback_url' option

What it means

validateOptions throws INVALID_DATA when callback_url is absent. This is the URL the IdP redirects to after authentication and must match what is registered with the provider.

Source

Thrown at packages/modules/providers/auth-oidc/src/services/oidc.ts:51

  static validateOptions(options: OidcAuthProviderOptions) {
    if (!options.issuer) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC provider requires an 'issuer' option"
      )
    }

    assertSecureUrl(options.issuer, "issuer")

    if (!options.client_id) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC provider requires a 'client_id' option"
      )
    }

    if (!options.callback_url) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "OIDC provider requires a 'callback_url' option"
      )
    }
  }

  constructor(
    { logger, cache }: InjectedDependencies,
    options: OidcAuthProviderOptions
  ) {
    // @ts-ignore
    super(...arguments)
    this.config_ = options
    this.logger_ = logger
    this.engine_ = new OidcEngine(options, cache)
  }

  // The same OIDC package is registered once per IdP (okta, auth0, ...), so the

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Add callback_url pointing at your Medusa auth callback route (customer: https://<host>/auth/customer/<provider-id>/callback; admin: the admin callback route).
2. Register the exact same URL (scheme, host, port, path) in the IdP's allowed redirect URIs.
3. Use env vars per environment so local (http://localhost:8000/...) and production URLs don't collide.

Example fix

// before
options: { issuer: "...", client_id: "..." }
// after
options: { issuer: "...", client_id: "...", callback_url: `${process.env.MEDUSA_BACKEND_URL}/auth/customer/google/callback` }

if (!process.env.OIDC_CALLBACK_URL) {
  throw new Error("OIDC_CALLBACK_URL is not set; cannot configure the oidc auth provider")
}

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

try { OidcAuthService.validateOptions(options) } catch (e) { if (e instanceof MedusaError && /'callback_url'/.test(e.message)) { /* report config error */ } throw e }

When it happens

Trigger: Provider options omit callback_url or reference an unset env var; Medusa therefore fails validation during registration of the auth provider at boot.

Common situations: Forgetting that OIDC (unlike other strategies) requires an explicit callback_url; changing the public host/port without updating the callback env var; mismatch between the configured URL and the IdP's registered redirect URI list (the latter surfaces later as an IdP-side error, so configure them together).

Related errors

• OIDC engine requires a 'callback_url' option
• OIDC provider requires an 'issuer' option
• OIDC provider requires a 'client_id' option
• OIDC '${label}' must be a valid URL
• Github callbackUrl is required

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