medusajs/medusa · error · MedusaError

Invalid TOTP code

Error message

Invalid TOTP code

What it means

The submitted TOTP code failed verification against the factor's stored secret (typically outside the allowed time window). This is a NOT_ALLOWED business rejection, not a crash.

Source

Thrown at packages/modules/auth/src/providers/mfa/totp.ts:148

    if (factor.provider !== this.method) {
      throw new MedusaError(
        MedusaError.Types.INVALID_DATA,
        "Only TOTP MFA factors can be verified with this method"
      )
    }

    if (factor.status === "disabled") {
      throw new MedusaError(
        MedusaError.Types.NOT_ALLOWED,
        "Disabled MFA factors cannot be verified"
      )
    }

    const valid = this.verifyCode_(factor, data.code)

    if (!valid) {
      throw new MedusaError(MedusaError.Types.NOT_ALLOWED, "Invalid TOTP code")
    }

    const verifiedFactor =
      factor.status === "pending"
        ? await this.authMfaFactorService_.update(
            { id: factor.id, status: "enabled" },
            sharedContext
          )
        : factor

    return await this.serializeFactor_(verifiedFactor)
  }

  async verify(
    data: { auth_identity_id: string; code: string },
    sharedContext: Context = {}
  ): Promise<boolean> {
    const [factor] = await this.authMfaFactorService_.list(

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Re-scan the QR / re-enter the current 6-digit code and retry
2. Sync the authenticator app's time (most apps have a 'time sync' setting) and verify server NTP
3. If it persists, delete the pending factor and restart TOTP setup

try { await verifySetup(...) } catch (e) { if (e.message === 'Invalid TOTP code') { /* prompt re-entry, sync device time */ } throw e }

When it happens

Trigger: confirmAuthMfaFactor/verifySetup where data.code doesn't match the current time-based code from the secret — wrong device clock, typo, drifted server time, or old code already used.

Common situations: Phone clock out of sync; user scanning QR with the wrong account entry; server clock drift; replaying an old code after page refresh.

Related errors

• An active TOTP factor already exists for this auth identity
• Only TOTP MFA factors can be verified with this method
• Disabled MFA factors cannot be verified
• Invalid MFA verification code
• INVALID_DATA

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