Troubleshooting Guide

Solutions to common issues with Guard Dog. If you don't find your issue here, check the FAQ or visit the WordPress.org support forums.

Emergency: Locked Out of Site

Scenario 1: Forgot Custom Login URL

What happened: You enabled custom login URL but forgot what you set it to.

Quick fix via FTP/File Manager:

1. Connect to your site via FTP or cPanel File Manager
2. Navigate to /wp-content/plugins/
3. Rename guard-dog folder to guard-dog-disabled
4. Access your site via normal /wp-login.php
5. Log in to WordPress admin
6. Rename folder back to guard-dog
7. Go to Guard Dog settings and note/change your login URL

Fix via database:

1. Access phpMyAdmin or database tool
2. Go to the wp_options table
3. Find row where option_name = guard_dog_login_slug
4. The option_value shows your custom login URL
5. Change it or delete the row to disable custom URL

Fix via wp-config.php:

1. Edit wp-config.php via FTP
2. Add this line before /* That's all, stop editing! */:

   define('GUARD_DOG_BYPASS', true);
   

3. Access /wp-login.php normally
4. Log in and fix settings
5. Remove the line from wp-config.php after fixing!

Scenario 2: Locked Out by IP Whitelist

What happened: Enabled site-wide blocking or IP whitelist without adding your IP.

Fix via database:

1. Access phpMyAdmin
2. Go to wp_options table
3. Find guard_dog_site_wide_blocking and set value to 0
4. Or find guard_dog_ip_whitelist and add your IP
5. Save changes

Fix via FTP:

1. Rename Guard Dog plugin folder to disable it
2. Access site normally
3. Fix settings
4. Rename folder back

Scenario 3: Locked Out by Failed Login Attempts

What happened: Too many failed login attempts, now locked out.

Options:

Wait it out:

• Lockout expires automatically (usually 15-30 minutes)
• Simplest solution if you can wait

Database fix:

1. Access phpMyAdmin
2. Find table: wp_guard_dog_login_attempts
3. Find your IP address in the table
4. Delete that row or set lockout_expiry to past date
5. You can immediately log in

FTP fix:

1. Disable plugin temporarily (rename folder)
2. Log in normally
3. Re-enable plugin
4. Adjust login limiting settings if needed

Scenario 4: Lost 2FA Device and Recovery Codes

What happened: Can't access authenticator app and don't have recovery codes.

Fix via admin assistance:

• Contact another site administrator
• They can disable 2FA on your account
• Then log in with just password and re-setup 2FA

Fix via database:

1. Access phpMyAdmin
2. Go to wp_usermeta table
3. Find your user ID (check wp_users table)
4. Delete rows where:
   • user_id = your ID
   • meta_key = _guard_dog_totp_enabled
5. This disables 2FA for your account

Fix via FTP:

1. Temporarily disable Guard Dog plugin
2. Log in with just password
3. Re-enable plugin
4. Set up 2FA again with new device

Installation & Setup Issues

Plugin Won't Activate

Error: "The plugin does not have a valid header"

Cause: Incomplete plugin files or corrupted download

Fix:

1. Deactivate and delete the plugin
2. Re-download from WordPress.org
3. Upload fresh copy
4. Activate

Error: "PHP Fatal error: Cannot redeclare class"

Cause: Plugin files exist in multiple locations

Fix:

1. Check /wp-content/plugins/ for duplicate folders
2. Remove duplicate guard-dog folders
3. Keep only one copy

Error: "This plugin requires PHP 7.4 or higher"

Cause: Your server uses PHP 7.3 or older

Fix:

1. Contact your hosting provider
2. Request PHP upgrade to 7.4 or higher (8.0+ recommended)
3. Most hosts allow this via cPanel

Database Tables Not Created

Symptoms: Plugin active but features don't work, "table doesn't exist" errors

Fix:

1. Deactivate Guard Dog
2. Reactivate Guard Dog
3. Check if tables now exist (via phpMyAdmin)

Manual table creation (advanced):

If deactivate/reactivate doesn't work, check PHP error logs for database errors. You may need to create tables manually or contact hosting support.

Settings Won't Save

Symptoms: Click "Save Changes" but settings don't persist

Possible causes:

1. File permissions issue

   • WordPress can't write to database
   • Check file ownership and permissions

2. PHP timeout

   • Large forms timeout before saving
   • Increase max_execution_time in php.ini

3. Memory limit

   • PHP runs out of memory
   • Increase memory_limit in php.ini or wp-config.php

4. Form size limit

   • POST data too large
   • Increase post_max_size in php.ini

5. Caching issue

   • Old values cached
   • Clear all caches (plugin, object, page cache)

Fix:

1. Clear all caches
2. Try in different browser (incognito mode)
3. Check PHP error logs
4. Contact hosting support to increase limits
5. Test with other plugins disabled (conflict check)

Feature-Specific Issues

Custom Login URL Issues

Issue: Both URLs show 404

Symptoms: Custom login URL and /wp-login.php both give 404

Fix:

1. Go to Settings → Permalinks
2. Click "Save Changes" (flushes rewrite rules)
3. Test both URLs again

Issue: Redirect loop when accessing custom URL

Cause: Conflicting plugin or theme redirect

Fix:

1. Disable other security plugins
2. Switch to default WordPress theme temporarily
3. Clear .htaccess redirects
4. Check for hardcoded redirects in theme

Issue: Custom URL works but other features break

Symptoms: Password reset doesn't work, logout fails, etc.

Cause: Theme or plugin using hardcoded URLs

Fix:

• Contact theme/plugin developer
• Theme should use wp_login_url() function
• Never hardcode /wp-login.php

CAPTCHA Issues

Issue: CAPTCHA not appearing

Causes & Fixes:

1. JavaScript error:

   • Open browser console (F12)
   • Look for errors
   • Disable conflicting plugins

2. Wrong API keys:

   • Verify Site Key and Secret Key
   • Check they're from correct provider
   • Re-copy from provider dashboard

3. Domain not registered:

   • Add your domain in CAPTCHA provider dashboard
   • For localhost: add localhost to allowed domains

4. Ad blocker:

   • Disable ad blocker
   • Test in incognito mode
   • Ad blockers often block CAPTCHA scripts

5. Theme CSS conflict:

   • CAPTCHA may be hidden by CSS
   • Inspect element to check
   • Add custom CSS to position correctly

Issue: CAPTCHA appears but verification always fails

Causes:

1. Wrong Secret Key:

   • Secret Key doesn't match Site Key
   • Re-copy both keys

2. Domain mismatch:

   • Your domain isn't registered with provider
   • Register it in provider dashboard

3. Server firewall:

   • Server blocking API calls to CAPTCHA provider
   • Contact hosting support

4. reCAPTCHA v3 score threshold too strict:

   • Lower threshold to 0.3 or 0.4
   • Test and gradually increase

Issue: Different CAPTCHA appears on mobile

This is normal – Some providers show different challenges on different devices. Test on actual mobile devices to ensure it works.

Two-Factor Authentication Issues

Issue: "Invalid verification code" error

Causes & Fixes:

1. Time sync issue:

   • Phone clock out of sync with server
   • Enable automatic time sync on phone
   • Check authenticator app time sync setting

2. Code expired:

   • Codes change every 30 seconds
   • Wait for new code to appear
   • Enter immediately

3. Wrong account in app:

   • Multiple accounts in authenticator
   • Ensure you're using code for correct site

4. Typing error:

   • Enter exactly as shown (no spaces)
   • Be careful with similar characters (0 vs O)

Issue: QR code won't scan

Fixes:

1. Increase screen brightness
2. Clean camera lens
3. Move closer/farther from screen
4. Use manual entry:
   • Click "Can't scan?"
   • Enter secret key manually in app

Issue: Lost recovery codes

If you can still log in:

1. Go to your user profile
2. Generate new recovery codes
3. Save them securely this time

If you can't log in:

• See Locked Out – Lost 2FA Device above

Issue: Email 2FA codes not arriving

Causes:

1. Email provider not configured:

   • Check Settings → Email Provider
   • Verify credentials are correct

2. Spam folder:

   • Check spam/junk mail
   • Add sender to safe list

3. Wrong email address:

   • Check user's email in profile
   • Verify it's correct

4. Email delivery delay:

   • Wait 1-2 minutes
   • Check provider dashboard for errors

Fix:

• Configure or verify email provider settings
• Test email sending
• Use app-based 2FA as more reliable alternative

Login Attempt Limiting Issues

Issue: Legitimate users getting locked out frequently

Causes:

1. Settings too strict
2. Users mistyping passwords
3. Shared IP (office/school)

Fixes:

Adjust settings:

• Increase Maximum Retries to 7-10
• Keep lockout duration reasonable (15-30 min)

Whitelist IPs:

• Add office/home IPs to IP Whitelist
• Whitelisted IPs never get locked out

User education:

• Tell users to use password managers
• Reduce typos

Issue: Lockouts not working (bots still trying unlimited attempts)

Causes:

1. Feature disabled
2. IP on whitelist
3. Cache serving old data

Fixes:

1. Verify feature is enabled in Login Security settings
2. Check IP isn't whitelisted
3. Clear all caches
4. Check Activity Log to verify lockouts are being recorded

Access Control Issues

Issue: IP whitelist not working

Symptoms: Whitelisted IP still blocked

Causes:

1. Wrong IP format:

   • Typo in IP address
   • Extra spaces
   • Wrong CIDR notation

2. Dynamic IP changed:

   • Your IP changed since adding to whitelist
   • Check current IP vs. whitelisted IP

3. IPv6 vs IPv4:

   • Added IPv4 but server sees IPv6
   • Add both versions

4. Behind proxy/CDN:

   • WordPress sees proxy IP instead of your actual IP
   • Configure reverse proxy settings first (see Reverse Proxy / CDN Issues)
   • Then whitelist your real IP, not the proxy IP

Fix:

1. First, configure reverse proxy settings if applicable (see Reverse Proxy / CDN Issues)
2. Verify your current IP (whatismyipaddress.com)
3. Check what Guard Dog detects (Sessions -> Settings -> "Detected IP")
4. Whitelist the IP Guard Dog is detecting
5. Remove old/wrong entries

Issue: Accidentally enabled site-wide blocking

Symptoms: Entire site shows "Access Denied"

Fix:

• See Locked Out – IP Whitelist above

Activity Log Issues

Issue: Events not being logged

Causes:

1. Event type disabled:

   • Check Event Settings
   • Enable desired event types

2. Database error:

   • Check PHP error logs
   • Table may be corrupted

3. Caching:

   • Old data being displayed
   • Clear caches and refresh

Fix:

1. Enable event types in Activity Log settings
2. Check PHP error logs for database errors
3. Clear caches

Issue: Too many log entries, database growing

Symptoms: Activity log table very large, site slowing down

Fix:

Immediate:

1. Go to Settings → Data Management
2. Clear logs older than 30 days
3. This provides immediate relief

Long-term:

1. Enable automatic cleanup (90-day retention)
2. Disable verbose event types:
   • Uncheck "Post Updated"
   • Uncheck "Profile Updated"
   • Keep security events only
3. Export logs before clearing (for records)

Issue: Can't export logs

Causes:

• Memory limit too low
• Too many entries
• Server timeout

Fix:

1. Filter logs to smaller dataset
2. Export in batches (by date range)
3. Increase PHP memory limit
4. Contact hosting support

Temporary User Access Issues

Issue: Access link not working

Symptoms: Clicking link doesn't log user in

Causes:

1. User expired:

   • Past expiry date
   • Automatically deleted

2. Login limit reached:

   • Used all allowed logins
   • User deleted

3. Link incomplete:

   • Didn't copy full URL
   • Missing token parameter

4. User manually deleted:

   • Admin deleted the user
   • Link no longer valid

Fix:

• Create new temporary user
• Send new access link
• Verify full link is copied

Issue: Can't create temporary user

Error messages:

"Username already exists":

• Choose different username
• Previous temp user may still exist

"Invalid email":

• Use proper email format
• Check for typos

General errors:

• Check PHP error logs
• Verify database tables exist
• Try different browser

Reverse Proxy / CDN Issues

All IP Shift Alerts Show the Same IP Address

Symptoms: Every IP shift alert email shows the same IP address (e.g., a Google Cloud, Cloudflare, or AWS IP), regardless of which user triggered the alert or where they are located.

Root cause: Your site is behind a reverse proxy, CDN, or load balancer, and Guard Dog is detecting the proxy's IP address instead of visitors' real IPs. When some requests arrive without forwarded headers (cache warming, health checks, internal requests), REMOTE_ADDR returns the proxy IP, triggering a false IP shift.

Fix:

1. Go to Guard Dog -> Sessions -> Settings
2. Scroll to Reverse Proxy / Load Balancer
3. Set IP Detection Method for your infrastructure:
   • Cloudflare: Select "Cloudflare"
   • Kinsta / Google Cloud: Select "X-Forwarded-For"
   • WP Engine: Select "X-Forwarded-For"
   • AWS ELB / ALB: Select "X-Forwarded-For"
   • Nginx reverse proxy: Select "X-Real-IP" or "X-Forwarded-For"
4. Add your proxy's IP address(es) to Trusted Proxy IPs
5. Save settings
6. Verify the Detected IP field shows your real IP, not the proxy IP

How to find your proxy IP: The IP address that appears in every false alert is your proxy's IP. You can also check the Activity Log for an IP that appears across many different users.

Guard Dog Shows Proxy IP Instead of Real Visitor IP

Symptoms: The "Detected IP" field, Activity Log, or session details show your proxy/CDN infrastructure IP for all visitors.

Diagnosis steps:

1. Check current detection: Go to Sessions -> Settings and look at the "Detected IP" row. If it shows an internal/infrastructure IP (like 10.x.x.x, 172.x.x.x, or your CDN's IP), configuration is needed.

2. Identify your proxy type:

   • Check with your hosting provider
   • Common setups: Cloudflare (uses CF-Connecting-IP), Nginx (uses X-Forwarded-For or X-Real-IP), AWS ELB (uses X-Forwarded-For)

3. Configure detection method:

   • Set the IP Detection Method to match your proxy type
   • Add proxy IPs to Trusted Proxy IPs
   • Save and verify with "Detected IP"

4. If "Auto" mode doesn't work: Switch to the specific header for your infrastructure. Auto mode checks all headers but may pick up the wrong one in complex multi-proxy setups.

IP-Based Security Features Not Working Behind Proxy

Symptoms: Login limiting, access control, or IP reputation features aren't working correctly. All visitors appear to have the same IP.

Cause: Without reverse proxy configuration, Guard Dog sees the proxy IP for all visitors, making IP-based features ineffective:

• Login limiting counts all attempts against one IP (the proxy)
• Access control whitelist/blacklist matches the proxy IP, not visitor IPs
• IP reputation checks the proxy's reputation, not the visitor's

Fix:

1. Configure reverse proxy settings as described above
2. After configuring, verify by checking Activity Log entries – different users should now show different IP addresses
3. Review and update any IP whitelist/blacklist entries that may have been set using the proxy IP

Reverse Proxy Settings Not Taking Effect

Symptoms: You configured the reverse proxy settings but Guard Dog still shows the wrong IP.

Check:

1. Correct detection method? Make sure you selected the right method for your proxy. Try different methods if unsure.

2. Proxy IP in trusted list? If you added trusted proxy IPs, make sure the actual proxy IP (REMOTE_ADDR) is included. The proxy IP is shown in parentheses next to "Detected IP" on the settings page.

3. Multiple proxy layers? If your traffic passes through multiple proxies (e.g., Cloudflare -> Nginx -> App), you may need to add all intermediate proxy IPs to the trusted list.

4. Valid IP/CIDR format? Trusted proxy IPs must be valid IPv4/IPv6 addresses or CIDR ranges. Invalid entries are silently ignored during sanitization.

5. Cache cleared? If using page caching, clear the cache after changing settings to ensure the settings page loads fresh.

Fallback: If nothing works, set detection method to "Auto" with an empty trusted proxy list. This reverts to default behavior which checks all common proxy headers.

Performance Issues

Site Running Slow After Installing Guard Dog

Diagnosis:

1. Check Activity Log table size:

   SELECT COUNT(*) FROM wp_guard_dog_activity_log;
   

   • If > 100,000 rows, clear old logs

2. Disable verbose event logging:

   • Turn off post updates, profile updates
   • Keep security events only

3. Check failed login attempts table:

   SELECT COUNT(*) FROM wp_guard_dog_login_attempts;
   

   • Clear old/expired lockouts

Fixes:

1. Clear old activity logs
2. Reduce events being logged
3. Enable automatic cleanup
4. Optimize database tables
5. Use object caching (Redis/Memcached)

Database Errors

Error: "Table 'wp_guard_dog_activity_log' doesn't exist"

Fix:

1. Deactivate Guard Dog
2. Reactivate Guard Dog
3. Tables should be recreated

If still failing, check:

• Database permissions (can WordPress create tables?)
• PHP error logs for specific error
• Contact hosting support

Error: "Duplicate column" or "Column already exists"

Cause: Database migration issue during update

Fix:

1. Note the error message
2. Post in support forums with:
   • Exact error message
   • WordPress version
   • PHP version
   • Guard Dog version

Compatibility Issues

Conflict with Other Security Plugins

Symptoms:

• Features not working
• Duplicate login forms
• Multiple CAPTCHA challenges
• Errors on login page

Common conflicts:

• Two plugins both modifying login URL
• Multiple 2FA plugins
• Multiple CAPTCHA plugins
• Multiple login limiting features

Fix:

1. Identify overlapping features
2. Disable one plugin's version of the feature
3. Or completely remove one plugin
4. Test thoroughly

Recommended:

• Use Guard Dog for login/2FA/CAPTCHA
• Use Wordfence/Sucuri for malware scanning
• Don't use multiple plugins for same feature

Theme Conflicts

Symptoms:

• Login page looks broken
• CAPTCHA in wrong position
• Buttons not working

Cause: Theme CSS or JavaScript interfering

Fix:

1. Switch to default WordPress theme (Twenty Twenty-Three)
2. Test if issue persists
3. If fixed: contact theme developer
4. They need to fix their theme's compatibility

WooCommerce Issues

Issue: WooCommerce My Account login doesn't work with custom login URL

Cause: WooCommerce may hardcode login URLs in some areas

Fix:

• WooCommerce should work automatically
• If issues persist, report to WooCommerce support
• They should use wp_login_url() function

Issue: WooCommerce checkout broken after enabling features

Rarely happens, but if it does:

1. Temporarily disable CAPTCHA
2. Check if issue persists
3. If fixed: CAPTCHA position issue
4. Contact theme developer

Debug Mode

Enabling Debug Logging

To troubleshoot issues:

1. Go to Guard Dog → Settings → Debug
2. Check "Enable Debug Logging"
3. Set Debug Level:
   • ERROR – Only critical errors
   • WARNING – Warnings and errors
   • INFO – General information
   • DEBUG – Verbose debugging (very detailed)
4. Save settings
5. Reproduce the issue
6. Download debug log

Reading Debug Logs

Debug logs show:

• Timestamp of events
• Log level (ERROR, WARNING, INFO, DEBUG)
• Component (which feature)
• Message
• Context data

Example log entry:

[2024-10-23 14:30:15] ERROR [Login URL] Direct access to wp-login.php blocked
IP: 203.0.113.50

Sharing Debug Logs

When reporting issues:

1. Enable debug logging
2. Reproduce the issue
3. Download the log
4. Remove any sensitive data (passwords, private keys)
5. Include relevant portion in support request

Getting Additional Help

Before Requesting Support

Gather this information:

1. WordPress version: Dashboard → Updates
2. PHP version: Site Health → Info → Server
3. Guard Dog version: Plugins page
4. Active plugins: List all active plugins
5. Theme: Active theme name and version
6. Error messages: Exact text of any errors
7. Debug log: Relevant portion if available

Where to Get Help

Free community support:

• WordPress.org Support Forums
• Response time: Usually within 24-48 hours

Before posting:

1. Search existing threads
2. Check FAQ and this troubleshooting guide
3. Gather information above

When posting:

1. Use descriptive title
2. Include all gathered information
3. Explain steps to reproduce
4. Mention what you've already tried

Reporting Bugs

To report a bug:

1. Verify it's reproducible
2. Check it's not already reported
3. Post in support forums with:
   • "[BUG]" in title
   • WordPress/PHP versions
   • Steps to reproduce
   • Expected vs actual behavior
   • Screenshots if applicable

---

← FAQ | Documentation Home | Best Practices →