medusajs/medusa · critical · MedusaError

OIDC provider requires an 'issuer' option

Error message

OIDC provider requires an 'issuer' option

What it means

The auth-oidc provider service validates its options at startup via static validateOptions; it throws INVALID_DATA when issuer is missing. The issuer URL is what openid-client uses for discovery, so it is mandatory.

Source

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

type InjectedDependencies = {
  logger: Logger
  cache?: ICacheService
}

// A generic failure message returned to the client; the detailed cause is only ever logged server-side.
const GENERIC_AUTH_ERROR = "Authentication failed"

export class OidcAuthService extends AbstractAuthModuleProvider {
  static identifier = "oidc"
  static DISPLAY_NAME = "OpenID Connect"

  protected readonly config_: OidcAuthProviderOptions
  protected readonly logger_: Logger
  protected readonly engine_: OidcEngine

  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"

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Set issuer in the provider options to your IdP's discovery base URL (e.g. https://accounts.google.com or https://auth.example.com/realms/main).
2. Verify the URL responds at <issuer>/.well-known/openid-configuration.
3. If sourced from env, confirm the variable is set where Medusa actually runs and restart the server.

Example fix

// before
options: { client_id: "...", callback_url: "..." }
// after
options: { issuer: process.env.OIDC_ISSUER, client_id: "...", callback_url: process.env.OIDC_CALLBACK_URL }

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

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

try { OidcAuthService.validateOptions(options) } catch (e) { if (e instanceof MedusaError && e.type === MedusaError.Types.INVALID_DATA) { /* report config error before boot */ } throw e }

When it happens

Trigger: Registering the oidc auth provider in medusa-config.js without an issuer option, or with issuer: undefined because an env var is unset.

Common situations: Env var (e.g. OIDC_ISSUER) not set in the deployment environment; typo in the key name (e.g. issuerUrl); config scaffolded from a template that left issuer blank.

Related errors

• OIDC engine requires a 'callback_url' 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/7bb7dbc853d8dea2. Report an issue: GitHub.