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:

1. Open email application
2. Navigate to Spam/Junk folder
3. Search for sender: [your-domain]
4. If found, mark as "Not Spam"
5. Move to inbox
6. 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:

1. Look at verification screen
2. Verify displayed email is correct
3. If wrong, update in profile (may need admin)

Admin steps to update:

1. WordPress Admin → Users → All Users
2. Find user, click "Edit"
3. Update "Email" field
4. Save changes
5. User tries login again

---

Solution 4: Check Email Server Configuration

Admin tasks:

---

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:

1. Sign up for service
2. Install WP Mail SMTP plugin
3. Configure API credentials
4. Test email delivery
5. Monitor delivery rates

---

Verification Code Expired

Issue: Code Expired Before Entry

---

Solution: Request New Code

User steps:

1. Click "Resend Code" link
2. Wait for new email (1-2 minutes)
3. Enter new code immediately
4. 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. This is a setting, not a filter — there is no attrua_2fa_code_expiration hook to add to functions.php.

User Access → Security → Two-factor, the code expiry field. It is read in minutes, defaults to 10, and is clamped to between 1 and 60 whatever you type. Raising it to 15 is the whole change.

---

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:

1. Carefully read each digit
2. Type manually (don't copy/paste)
3. Use most recent email
4. 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:

1. Check server time: Settings → General
2. Verify timezone is correct
3. Ensure server NTP sync enabled
4. 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:

1. Clear browser cache and cookies
2. Close all browser windows
3. Reopen browser
4. 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

1. WordPress Admin → Users → All Users
2. Find locked user
3. Click "Edit"
4. Scroll to "Two-Factor Authentication"
5. Click "Unlock Account" button
6. Save changes

Method 2: there is nothing to unlock

---

User Lost Email Access

Issue: Cannot Access Email for Verification

---

Admin Recovery Process

Option 1: Update Email Address

1. Verify user identity (phone, ID, etc.)
2. WordPress Admin → Users → All Users
3. Find user, click "Edit"
4. Update "Email" field with new address
5. Save changes
6. User can now log in with new email

---

Option 2: Temporarily Disable 2FA

1. Verify user identity
2. Edit user profile
3. Uncheck "Require 2FA for this user"
4. Save changes
5. User logs in without 2FA
6. User updates email in profile
7. 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:

1. Access server via FTP/SSH
2. Edit wp-config.php
3. Add line above "That's all, stop editing!"
4. Save file
5. Log in (2FA bypassed)
6. Update email or fix issue
7. Remove the line from wp-config.php
8. 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:

1. Install and activate WP Mail SMTP
2. Choose mailer (SendGrid, Mailgun, etc.)
3. Enter API credentials
4. Set From Email and From Name
5. Send test email
6. 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:

1. Settings → Attributes User Access → Security
2. Find "Require 2FA for Roles"
3. Verify user's role is checked
4. Save changes if modified

---

Solution 2: Check User-Specific Settings

User may be exempt:

1. Users → All Users → Find user
2. Click "Edit"
3. Scroll to 2FA settings
4. Check if "Exempt from 2FA" is checked
5. Uncheck if should require 2FA
6. 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:

1. Settings → Attributes User Access → Security
2. Verify "Enable Two-Factor Authentication" is ON
3. Save changes
4. Test with user account

---

Performance Issues with 2FA

Issue: Slow Code Generation/Delivery

---

Solution 1: Check Email Queue

Server-side queue:

1. Access server mail logs
2. Check for mail queue backup
3. Process queued emails
4. Increase mail send limits if needed

---

Solution 2: Get the mail off your own server

There is no attrua_2fa_async_email filter, and no background queue inside the plugin — a code is sent with wp_mail() during the request, so a slow mail transport is felt directly as a slow sign-in.

The fix is to stop sending through the server's own mailer. Configure SMTP with a transactional provider under User Access → Notifications → How mail leaves your site, which hands the message off in a few hundred milliseconds instead of waiting on a local queue. See checking email delivery.

---

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: check the right table

Two-factor keeps almost nothing in tables:

So a genuine "database error" during 2FA is about wp_attrua_totp_secrets or wp_usermeta, not a missing 2FA table:

SHOW TABLES LIKE 'wp_attrua_totp_secrets';
CHECK TABLE wp_attrua_totp_secrets;

If that table is missing, deactivating and reactivating Pro recreates it — the installer runs on activation. Do not delete it to force a rebuild: it holds every enrolled user's authenticator secret and backup codes, and they would all have to enrol again.

---

Emergency Recovery Procedures

Complete Site Lockout

All admins locked out:

Recovery steps:

1. Access server via FTP/SSH/cPanel
2. Navigate to WordPress root
3. Edit wp-config.php
4. Add: define('ATTRUA_DISABLE_2FA', true);
5. Save file
6. Log in as admin (2FA disabled)
7. Fix issues (update emails, check settings)
8. Remove line from wp-config.php
9. Test 2FA works correctly

---

Database Corruption

2FA tables corrupted:

Recovery:

1. Backup database
2. Drop 2FA tables
3. Deactivate plugin
4. Reactivate plugin (recreates tables)
5. Reconfigure 2FA settings
6. Test thoroughly

---

articleRelated articles

• 2FA Overview
• 2FA Configuration
• 2FA User Experience