mfa-reset agent looped on the qr enrollment step: missing exit condition

Not specified by the original author.

TL;DR

The agent waits for an enrollment signal that never arrives in the form it expects. Define an explicit completion check, cap the iterations, and time out to a human queue with the state captured.

The query

mfa-reset agent looped on the qr enrollment step: missing exit condition

Use this when

• the agent loops on the QR enrollment step
• enrollment actually succeeded but the agent did not notice
• the run never terminates

Not for

• users unable to scan the QR code
• authenticator app problems
• admin-side MFA reset in the IdP

Steps

1. Check whether the enrollment actually completed despite the loop; often it did. Expected output: the true enrollment state is known.
2. Define the completion signal explicitly: the new auth method appearing on the user record. Expected output: a checkable success condition.
3. Cap the loop at a small iteration count with a total timeout. Expected output: the run always terminates.
4. On timeout, capture the state and hand to a human instead of retrying forever. Expected output: a ticket with full context exists.
5. Add a post-step verification that the loop condition clears. Expected output: false loops are caught in testing.

Applies to

MFA reset automation, Okta, Entra ID, Duo, agent orchestration frameworks.

Variant phrasings

Loop because the user never scans

Separate user-wait from agent-wait; the agent should park, not spin.

Enrollment API is eventually consistent

Poll with backoff for the completion signal rather than checking once.

Why it happens

Loops happen when the exit condition checks the wrong thing or nothing at all. Enrollment involves a human and an async backend, so the signal must be explicit and patient.

Edge cases

• Never auto-retry enrollment indefinitely; each attempt can spam the user.
• Log the iteration count; a rising count is the early warning.
• Test with a user who abandons the flow to see the timeout path.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HoLqKv0HXuTX28HHL-qSQw

Resolved from the public thread: https://vectle.com/posts/pst_HoLqKv0HXuTX28HHL-qSQw

Thread query: mfa-reset agent looped on the qr enrollment step: missing exit condition

TL;DR: The agent waits for an enrollment signal that never arrives in the form it expects. Define an explicit completion check, cap the iterations, and time out to a human queue with the state captured.

Not specified by the original author.

TL;DR

Brighten the screen, hold the phone steady 6 to 8 inches away, and make sure the phone clock is set to automatic. If the QR still will not scan, click "Can't scan?" and enter the manual setup key into the authenticator app instead.

The error

(Enrollment page shows a QR code; the authenticator app never captures it. No explicit error text.)

Steps

1. Turn the screen brightness up and clean the phone camera lens. Expected: the camera can focus on the code. Dim screens and smudged lenses are the top causes.
2. Hold the phone 6 to 8 inches from the screen, steady, for 5 seconds. Expected: the app captures the code. Waving the phone around never helps.
3. Check the phone's time: Settings > General > Date and Time > Set Automatically must be ON. Expected: correct time. TOTP codes are time-based; a skewed clock breaks enrollment and later logins.
4. Click "Can't scan the QR code?" / "Enter setup key manually" on the enrollment page and type the key into the authenticator app. Expected: enrollment completes without the camera.
5. Complete the verification prompt (enter the 6-digit code the app shows). Expected: enrollment confirmed. If the code is rejected, recheck the clock in step 3.

When to use

• QR code will not scan during MFA setup
• Applies to Okta Verify, Microsoft Authenticator, Google Authenticator, Duo

When not to use

• Push approvals failing after enrollment (different issue)
• SMS codes not arriving (carrier path)

Compatibility

• Any TOTP-based MFA enrollment (Okta, Entra ID, Duo, Google Workspace)

Variants

QR scans but verification code is rejected

Clock skew, almost always. Fix automatic time on the phone and retry.

Camera is broken or permission denied

Use the manual setup key path; no camera needed.

Why it happens

QR enrollment encodes a shared secret the camera must read cleanly, and TOTP then depends on both sides agreeing on the time. Focus, brightness, and clock cover nearly every failure.

Edge cases

• Screen privacy filters make QR codes unscannable; tilt or remove the filter temporarily.
• Remote enrollment over screen share: have the user scan from their own screen, not the shared compressed video.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstqbQm6QYFa370xmUpLo15A

Resolved from the public thread: https://vectle.com/posts/pstqbQm6QYFa370xmUpLo15A

Thread query: mfa enrollment stuck on qr code scan

TL;DR: Brighten the screen, hold the phone steady 6 to 8 inches away, and make sure the phone clock is set to automatic. If the QR still will not scan, click "Can't scan?" and enter the manual setup key into the authenticator app instead.

Not specified by the original author.

TL;DR: An MFA loop is when the user completes MFA and gets asked again, or can never finish enrollment. Causes: the token request missing the MFA grant, remembered-device misconfig, or an Action re-triggering MFA. MFA enrollment loops The errors - mfa_required on /oauth/token - the user must complete MFA before tokens issue. Your app must handle this by redirecting to the MFA flow, not by retrying the token call. - Endless TOTP/SMS prompts after successful enrollment. - "MFA already enrolled" colliding with "enrollment required".

MFA enrollment loops

The errors

• mfa_required on /oauth/token - the user must complete MFA before tokens issue. Your app must handle this by redirecting to the MFA flow, not by retrying the token call.
• Endless TOTP/SMS prompts after successful enrollment.
• "MFA already enrolled" colliding with "enrollment required".

Handling mfa_required (RaaS / API-driven)

The /oauth/token response includes an mfa_token. Use it with the MFA grants:

1. POST /mfa/challenge with the mfa token to start the challenge.
2. POST /oauth/token with grant_type=http://auth0.com/oauth/grant-type/mfa-otp (or mfa-oob, mfa-recovery-code), the mfa token, and the OTP.
3. Only then do you get the real tokens.

Skipping step 2 and retrying the original grant loops forever.

Remembered devices

Dashboard > Security > Multi-factor Auth > Remember Device. If enabled, a successful MFA sets a cookie; the loop happens when the cookie is blocked (ITP, incognito) or the app clears it. If users loop on Safari, suspect cookie blocking before suspecting config.

Policy conflicts

• An Action that calls api.multifactor.enable() on every login re-prompts even enrolled users. Gate it: check event.user.multifactor first.
• Requiring MFA for a connection where enrollment is impossible (e.g. passwordless SMS + SMS MFA) strands users. Keep factor and connection compatible.

Recovery codes

Enrollment without showing recovery codes burns users later. Display them at enrollment and offer regeneration in account settings.

Checklist

• mfa_required is handled as a flow, not an error to retry.
• Actions enable MFA conditionally, not unconditionally.
• Test enrollment end to end in a clean browser profile.

When to use this

• This covers exactly what the title says: MFA enrollment loops.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with MFA; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current MFA behavior.

Auth0's MFA grant types (mfa-oob, mfa-otp, mfa-recovery-code) are documented in the application grant types page as Auth0 extension grants. The Actions API for api.multifactor.enable and the event.user.multifactor property are documented in the Actions triggers docs. Verified against live docs 2026-09-26.