medusajs/medusa · error · MedusaError

id_token is missing 'sub' claim

Error message

id_token is missing 'sub' claim

What it means

The decoded and signature-verified id_token from Medusa Cloud is missing the 'sub' (subject) claim, which the provider uses as the entity id for the auth identity. Without it the identity cannot be mapped, so authentication aborts.

Source

Thrown at packages/modules/auth/src/providers/medusa-cloud-auth.ts:224

        throw new Error("Invalid id_token")
      }
      payload = decoded
    } catch (err) {
      return {
        success: false,
        error: `Could not verify id_token: ${err.message}`,
      }
    }

    if (!payload.email_verified) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "Email not verified, cannot proceed with authentication"
      )
    }

    if (!payload.sub) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "id_token is missing 'sub' claim"
      )
    }

    const entity_id = payload.sub
    const userMetadata = {
      name: payload.name,
      email: payload.email,
      picture: payload.picture,
      given_name: payload.given_name,
      family_name: payload.family_name,
    }

    let authIdentity

    try {
      authIdentity = await authIdentityService.retrieve({

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Inspect the id_token payload (decode the middle segment) to confirm which claims are present
2. Fix the IdP/Cloud configuration so standard OIDC 'sub' is included in issued tokens
3. If testing, use a properly formatted JWT containing sub and email_verified

try { await validateCallback(...) } catch (e) { if (e.message.includes("missing 'sub'")) { /* flag IdP token config issue */ } throw e }

When it happens

Trigger: validateCallback receives an id_token whose payload lacks 'sub' — typically a misconfigured or nonstandard token issued by the identity provider, or a hand-crafted/debug token used in tests.

Common situations: Custom IdP configurations that drop standard OIDC claims; stale test fixtures with truncated JWTs; IdP version/config change that altered token claims.

Related errors

• UNAUTHORIZED
• Customer with this email already has an account
• The user is already authenticated and cannot accept an invit
• User ID not found
• User with id: ${id} was not found

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