Troubleshooting MFA

OTP code not accepted

Symptom:You enter the 6-digit code from your authenticator app and Nuxari returns "Invalid code" or "Code has expired", even though the code appears valid and unexpired in the app.

1. 1

   Sync your device clock to an NTP source

   On iOS: Settings > General > Date & Time, enable 'Set Automatically'. On Android: Settings > General Management > Date and Time, enable 'Automatic date and time'. On desktop: use your OS time sync settings. After syncing, try a new code immediately.

2. 2

   Enter the code quickly after it generates

   TOTP codes are valid for 30 seconds. Enter the code within the first 20 seconds of its validity window to avoid edge cases near the boundary. Watch the countdown indicator in your authenticator app.

3. 3

   Confirm you are using the correct account in your authenticator

   If you have multiple accounts in your authenticator app, verify you are reading the code from the Nuxari entry, not a similarly named service. The issuer label should read 'Nuxari' and show your registered email address.

4. 4

   Try a recovery code

   If OTP codes continue to fail, use one of the recovery codes you saved during MFA enrollment. Recovery codes bypass TOTP and allow you to log in. After logging in, re-enroll MFA from Settings > Security.

5. 5

   Contact your workspace admin to reset MFA

   If you cannot use OTP and have no recovery codes, a workspace admin can go to Settings > User Management, find your account, and click Reset MFA. This removes your current MFA enrollment so you can re-enroll on next login.

Lost access to authenticator device

Symptom: Your phone or hardware key is lost, stolen, or broken. You cannot generate a valid OTP code to complete login.

1. 1

   Use a recovery code

   If you saved recovery codes during MFA enrollment, enter one of them in the recovery code field on the MFA challenge screen. Each code can only be used once. After logging in successfully, immediately re-enroll a new authenticator device.

2. 2

   Ask a workspace admin to reset your MFA

   If you have no recovery codes, contact a workspace admin. The admin can go to Settings > User Management, find your account, and click Reset MFA. Once reset, you will be prompted to enroll a new MFA device on your next login.

3. 3

   Re-enroll your new device immediately after recovery

   After regaining access, go to Settings > Security > MFA and enroll your replacement device. Generate and securely store new recovery codes. Do not skip this step.

4. 4

   Revoke the lost device from your authenticator account (if applicable)

   If your authenticator app has cloud backup (Google Authenticator, Authy, or iCloud Keychain), sign into that account from another device and remove or revoke the lost device's access to prevent unauthorized use of any remaining session.

QR code not scanning

Symptom: During MFA enrollment, the QR code displayed on screen cannot be scanned by your authenticator app camera, or scanning does nothing.

1. 1

   Increase screen brightness

   Low screen brightness is the most common cause of scan failures. Increase your monitor or phone brightness to maximum before attempting to scan.

2. 2

   Adjust the distance between your phone and the screen

   Hold your phone 15–25 cm from the screen. Too close or too far can prevent the camera from focusing on the QR code. Move slowly while the camera autofocuses.

3. 3

   Use the manual entry code instead

   Below the QR code on the enrollment screen, there is a text link that reads 'Enter code manually' or 'Can't scan the QR code?'. Click it to reveal the 32-character secret key. In your authenticator app, choose 'Enter setup key' or 'Manual entry' and type the key. Set the type to TOTP and the period to 30 seconds.

4. 4

   Try a different authenticator app

   If your current authenticator app is outdated or buggy, try a different one such as Google Authenticator, Microsoft Authenticator, or Aegis (Android). After adding the account in the new app, verify a code is accepted before relying on it.

5. 5

   Disable display scaling if scanning from a monitor

   High DPI scaling on Windows or macOS can distort the QR code rendering. Temporarily set your display scaling to 100% for the enrollment step, or use the manual entry code option.

Recovery codes exhausted

Symptom: All recovery codes have been used and no more are available. You cannot complete MFA with your authenticator app either.

1. 1

   Contact your workspace admin for an MFA reset

   An admin can reset your MFA enrollment from Settings > User Management. After the reset, you will be prompted to enroll a new authenticator device on next login.

2. 2

   Complete re-enrollment and immediately generate new recovery codes

   After admin reset, log in and go through the MFA enrollment wizard. At the end, download and securely store the new recovery codes. Store them in a password manager or printed in a secure location — never in the same device as the authenticator.

3. 3

   Consider enrolling a backup authenticator device

   Nuxari allows enrolling multiple MFA methods. After your primary device is enrolled, enroll a secondary device or hardware key. This provides a fallback without depending on recovery codes.

MFA enforcement blocking login

Symptom:After entering credentials, users are required to enroll in MFA before they can access the workspace, or they see "MFA is required for this workspace" but are unable to complete enrollment due to a technical issue.

1. 1

   Understand why MFA is being enforced

   MFA enforcement is a workspace security policy set by a workspace admin in Settings > Security. When enforced, every user must enroll in MFA before accessing any workspace features. This is intentional and not a bug.

2. 2

   Complete enrollment during the forced enrollment flow

   When MFA is enforced and you have not enrolled, Nuxari presents an enrollment screen immediately after login. You cannot skip this step. Follow the prompts to scan the QR code with your authenticator app and confirm a valid code.

3. 3

   If enrollment fails technically, contact your admin

   If the enrollment screen returns an error (not a wrong code — an actual server error or blank screen), contact your workspace admin. The admin can temporarily exempt your account or contact Nuxari support on your behalf.

4. 4

   Admins: temporarily disable enforcement to unblock a user

   If enforcement is blocking a critical user who cannot enroll (e.g., a shared service account), an admin can go to Settings > Security and temporarily disable MFA enforcement to let the user in. Re-enable enforcement after the issue is resolved.

Cannot enroll in MFA

Symptom:The MFA enrollment page shows an error, the QR code fails to generate, or submitting the verification code during enrollment returns "Enrollment failed".

1. 1

   Refresh the enrollment page and try again

   The QR code is time-bounded. If you left the enrollment page open for more than 10 minutes without completing enrollment, the QR code may have expired. Refresh the page to generate a fresh QR code and start over.

2. 2

   Confirm you entered the right verification code to complete enrollment

   During enrollment, after scanning the QR code, you must enter a valid code from your authenticator app to confirm the setup. Enter the 6-digit code displayed in the app at that moment, not a code from a previous step.

3. 3

   Try the manual key entry method

   If scanning fails repeatedly, use manual entry (see 'QR code not scanning' above). Manual entry avoids camera and scanning issues entirely.

4. 4

   Check for browser interference

   Pop-up blockers or content security policy overrides in some browsers can prevent the enrollment page from fully loading. Try enrollment in a private browser window with extensions disabled.

5. 5

   Contact Nuxari support if enrollment returns a server error

   If the page returns a 500 error or 'Enrollment failed — please try again later', this is a server-side issue. Contact Nuxari support with the time of the attempt and your account email so the engineering team can investigate.