Two-Factor Authentication Troubleshooting (Pro)

Overview

This comprehensive troubleshooting guide covers all common Two-Factor Authentication issues with step-by-step solutions for both users and administrators.

User Cannot Receive Verification Code

Issue: Email Never Arrives

Solution 1: Check Spam/Junk Folder

Steps for user:

• Open email application

• Navigate to Spam/Junk folder

• Search for sender: [your-domain]

• If found, mark as “Not Spam”

• Move to inbox

• Add sender to contacts

Prevention:

Whitelist sender email address
Add domain to safe senders list
Configure email filters

Solution 2: Wait for Delivery

Email servers can delay:

• Typical: 10-30 seconds

• Occasional: 1-3 minutes

• Rare: 5-10 minutes

Action:

Wait 3-5 minutes before requesting resend

Check spam folder while waiting

Avoid clicking “Resend” repeatedly

Solution 3: Verify Email Address

Check correct email:

• Look at verification screen

• Verify displayed email is correct

• If wrong, update in profile (may need admin)

Admin steps to update:

• WordPress Admin → Users → All Users

• Find user, click “Edit”

• Update “Email” field

• Save changes

• User tries login again

Solution 4: Check Email Server Configuration

Admin tasks:

• Test email delivery: Settings → Email → Send Test
• Check SMTP settings: If using SMTP plugin, verify credentials
• Review server logs: Look for email delivery errors
• Check sending limits: Ensure not hitting hourly/daily limits
• Verify DNS records: SPF, DKIM, DMARC configured

Solution 5: Use Transactional Email Service

If built-in mail unreliable: Recommended services:

• SendGrid

• Mailgun

• Amazon SES

• Postmark

• SparkPost

Benefits:

• ✅ Guaranteed delivery

• ✅ High delivery rates

• ✅ Detailed analytics

• ✅ Professional sender reputation

Setup:

• Sign up for service

• Install WP Mail SMTP plugin

• Configure API credentials

• Test email delivery

• Monitor delivery rates

Verification Code Expired

Issue: Code Expired Before Entry

Solution: Request New Code

User steps:

• Click “Resend Code” link

• Wait for new email (1-2 minutes)

• Enter new code immediately

• Complete within 10 minutes

Best practice:

Keep email app open

Copy code before switching apps

Enter code promptly

Don’t multitask during login

Admin Configuration (If Frequent Issue):

Consider longer expiration:

// Add to functions.php or custom plugin
add_filter('attrua_2fa_code_expiration', function() {
    return 15 * MINUTE_IN_SECONDS; // 15 minutes instead of 10
});

Invalid Verification Code Error

Issue: Code Shows as Invalid

Solution 1: Verify Code Accuracy

Common mistakes:

• Similar characters: 0 vs O, 1 vs l, 8 vs B

• Extra spaces: Copy/paste may add spaces

• Wrong code: Using old email if multiple received

Correct approach:

• Carefully read each digit

• Type manually (don’t copy/paste)

• Use most recent email

• Double-check before submitting

Solution 2: Use Latest Code Only

Multiple emails = confusion:

Email 1: Code 123456 (invalid after Email 2 sent)

Email 2: Code 789012 (current valid code)

Email 3: Code 345678 (most recent – use this!)

Rule: Only the most recent code is valid. All previous codes invalidate automatically.

Solution 3: Check for Timing Issues

Server time sync: Admin diagnostic:

• Check server time: Settings → General

• Verify timezone is correct

• Ensure server NTP sync enabled

• Check PHP date/time functions

If times are off:

Verification codes won’t match

Fix server time configuration

Restart PHP-FPM or Apache

Test again

Solution 4: Clear Browser Cache

User steps:

• Clear browser cache and cookies

• Close all browser windows

• Reopen browser

• Try login again with fresh code

Account Locked After Failed Attempts

Issue: Too Many Failed Verification Attempts

For Users: Wait It Out

Lockout duration: 30 minutes (default) During lockout:

❌ Cannot request new codes

❌ Cannot attempt login

✓ Can contact administrator

✓ Can wait for automatic unlock

After 30 minutes:

Account automatically unlocks

Can attempt login again

Get fresh verification code

For Admins: Manual Unlock

Unlock user immediately: Method 1: User Profile

• WordPress Admin → Users → All Users

• Find locked user

• Click “Edit”

• Scroll to “Two-Factor Authentication”

• Click “Unlock Account” button

• Save changes

Method 2: Database (Advanced)

-- Find user lockout records
SELECT * FROM wp_attrua_2fa_lockouts 
WHERE user_id = [USER_ID];

-- Remove lockout
DELETE FROM wp_attrua_2fa_lockouts 
WHERE user_id = [USER_ID];

User Lost Email Access

Issue: Cannot Access Email for Verification

Admin Recovery Process

Option 1: Update Email Address

• Verify user identity (phone, ID, etc.)

• WordPress Admin → Users → All Users

• Find user, click “Edit”

• Update “Email” field with new address

• Save changes

• User can now log in with new email

Option 2: Temporarily Disable 2FA

• Verify user identity

• Edit user profile

• Uncheck “Require 2FA for this user”

• Save changes

• User logs in without 2FA

• User updates email in profile

• Re-enable 2FA

Option 3: Emergency Access (wp-config.php) For admin lockouts:

// Add to wp-config.php temporarily
define('ATTRUA_DISABLE_2FA', true);

Steps:

• Access server via FTP/SSH

• Edit wp-config.php

• Add line above “That’s all, stop editing!”

• Save file

• Log in (2FA bypassed)

• Update email or fix issue

• Remove the line from wp-config.php

• Test 2FA works again

Email Going to Spam Folder

Issue: Codes Consistently in Spam/Junk

Solution 1: Configure Email Authentication

Setup SPF Record:

Add to DNS:

v=spf1 include:_spf.yourdomain.com ~all

Setup DKIM:

Contact hosting provider for DKIM keys

Add DKIM DNS records

Verify signature in email headers

Setup DMARC:

Add to DNS:

_dmarc.yourdomain.com TXT “v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com”

Solution 2: Use Professional SMTP

Install WP Mail SMTP plugin:

• Install and activate WP Mail SMTP

• Choose mailer (SendGrid, Mailgun, etc.)

• Enter API credentials

• Set From Email and From Name

• Send test email

• Verify inbox delivery

Solution 3: Improve Email Content

Avoid spam triggers:

❌ ALL CAPS SUBJECT LINES

❌ Multiple exclamation marks!!!

❌ “Click here” repeated many times

❌ Suspicious links

✓ Professional sender name

✓ Clear, concise subject

✓ Minimal HTML

✓ Text-based code display

2FA Not Required When Expected

Issue: User Logs In Without 2FA Prompt

Solution 1: Check Role Configuration

Admin verification:

• Settings → Attributes User Access → Security

• Find “Require 2FA for Roles”

• Verify user’s role is checked

• Save changes if modified

Solution 2: Check User-Specific Settings

User may be exempt:

• Users → All Users → Find user

• Click “Edit”

• Scroll to 2FA settings

• Check if “Exempt from 2FA” is checked

• Uncheck if should require 2FA

• Save changes

Solution 3: Check “Remember Me” Status

Long-term sessions:

If “Remember Me” was checked on previous login:

• 2FA may be skipped for 14-30 days

• Clear browser cookies to force 2FA

• Or wait for session to expire

Solution 4: Verify 2FA is Enabled Globally

Admin check:

• Settings → Attributes User Access → Security

• Verify “Enable Two-Factor Authentication” is ON

• Save changes

• Test with user account

Performance Issues with 2FA

Issue: Slow Code Generation/Delivery

Solution 1: Check Email Queue

Server-side queue:

• Access server mail logs

• Check for mail queue backup

• Process queued emails

• Increase mail send limits if needed

Solution 2: Optimize Email Sending

Use asynchronous sending:

// Send emails in background (requires setup)
add_filter('attrua_2fa_async_email', '__return_true');

Solution 3: Monitor Sending Limits

Hosting restrictions:

Shared hosting often limits:

• Emails per hour: 100-500

• Emails per day: 500-2000

Check hosting plan limits

Upgrade if necessary

Use transactional service instead

Database Errors with 2FA

Issue: Database Connection Errors

Solution: Repair Database Tables

Check tables exist:

SHOW TABLES LIKE 'wp_attrua_2fa_%';

Should show:

wp_attrua_2fa_codes

wp_attrua_2fa_lockouts

wp_attrua_2fa_history

Repair if needed:

• Backup database first!

• Deactivate plugin

• Delete tables

• Reactivate plugin (recreates tables)

• Test 2FA functionality

Emergency Recovery Procedures

Complete Site Lockout

All admins locked out: Recovery steps:

• Access server via FTP/SSH/cPanel

• Navigate to WordPress root

• Edit wp-config.php

• Add: define(‘ATTRUA_DISABLE_2FA’, true);

• Save file

• Log in as admin (2FA disabled)

• Fix issues (update emails, check settings)

• Remove line from wp-config.php

• Test 2FA works correctly

Database Corruption

2FA tables corrupted: Recovery:

• Backup database

• Drop 2FA tables

• Deactivate plugin

• Reactivate plugin (recreates tables)

• Reconfigure 2FA settings

• Test thoroughly