Troubleshooting Common Issues

This guide covers the most common problems and their solutions when setting up and running the XYZ Age Verification plugin.

Setup Issues

Setup Checklist Shows a Red X

The settings page includes a checklist that validates your configuration. Here's what each item means and how to fix it:

API Key: Missing

Go to Settings > Age Verification and enter your API key.
If you don't have one, register for a free plan using the email form on the settings page.

Cookie Signing Key: Missing

Click "Fetch from API" on the settings page. The key will be retrieved automatically.
If this fails, check that your API key is valid and the API is reachable.

Age-Gate Page: Not found

Create a WordPress page with the slug age-gate.
The slug must be exactly age-gate, not "age_gate" or "agegate" or anything else.
To check/change the slug: edit the page, open the settings panel, and look for "URL" or "Permalink."

MU Plugin: Not installed

Copy xyz-age-gate-redirect.php from wp-content/plugins/xyz-age-verify-free/mu-plugin/ to wp-content/mu-plugins/.
Create the mu-plugins directory if it doesn't exist.
Make sure the file is directly in mu-plugins/, not in a subdirectory.

API Status: Unreachable

Check your server's outbound connectivity.
Verify that your hosting provider does not block outbound HTTPS requests.
Try again in a few minutes — the API may be briefly unavailable for maintenance.

"Could not reach API" When Registering

This usually means the WordPress AJAX handler could not connect to the XYZ API from your server. Common causes:

Firewall blocking outbound requests — some hosting providers restrict which external URLs PHP can connect to. Check with your host.
PHP cURL extension not installed — WordPress needs cURL for wp_remote_post(). Check your PHP info for the curl module.
Invalid API URL — the plugin uses the default API URL. If you've modified it (developer mode), verify it's correct.

Age Gate Not Activating

Visitors Are Not Being Redirected

If visitors from configured regions can access your site without seeing the age gate:

Check that the MU plugin is installed. Go to Plugins > Must-Use in your WordPress admin. You should see xyz-age-gate-redirect.php listed.
Check Cloudflare proxying. The DNS record for your domain must be set to "Proxied" (orange cloud) in Cloudflare, not "DNS only" (gray cloud).
Check that regions are configured. Go to Settings > Free Plan > Regions and verify you have at least one region with the action set to "Verify."
Check the region codes. Make sure the country code matches what Cloudflare reports. You can verify by looking at the CF-IPCountry header in browser developer tools (Network tab > click a request > Headers).
Check for page caching. If you're using a page cache plugin, cached pages bypass PHP entirely and the MU plugin never runs. See Caching Compatibility.

Redirect Loop

If you see a redirect loop (the browser says "this page redirected you too many times"):

Check the age-gate page slug. It must be exactly age-gate. If the slug is wrong, the MU plugin redirects to a URL that doesn't match the age-gate page, which triggers another redirect.
Check for double redirects. Some security plugins or hosting configurations add their own redirects. Temporarily disable other redirect-related plugins to isolate the issue.
Check test mode. If test mode is enabled and you're adding ?reg= to the age-gate page itself, you'll get a loop. The ?reg= parameter should be added to a content page, not the age-gate page.

Age Gate Shows But Immediately Redirects Back

If the visitor briefly sees the age gate page but is immediately sent back to the content page:

Check for a stale verification cookie. Clear cookies in your browser or use an incognito window.
Check the shortcode. Make sure the age-gate page contains [xyz_age_verify] exactly. A typo in the shortcode will cause the page to render without the verification interface, and the MU plugin may interpret the page load as successful.

Verification Issues

QR Code Does Not Appear

The QR code is generated locally using bundled JavaScript. If it doesn't appear, check your browser's developer console for JavaScript errors.
Ensure the shortcode [xyz_age_verify] is on the page (not embedded inside another shortcode or block).

Verification Completes But Visitor Is Not Redirected

After completing verification on their phone, the desktop page should automatically detect the completion and redirect the visitor. If this doesn't happen:

Check that the polling AJAX handler is working. Open browser developer tools, switch to the Network tab, and look for POST requests to admin-ajax.php. They should be returning 200 status codes.
Check session expiration. Verification sessions expire after a configured period. If the visitor took too long, the session may have expired.
Check the API Status on the settings page. If the API is unreachable, the polling requests cannot get status updates.

Verification Passes But Cookie Is Not Set

If verification succeeds but the visitor is asked to verify again on the next page:

Check HTTPS. The verification cookie has the Secure flag set, so it's only sent over HTTPS. If your site serves any pages over HTTP, the cookie won't be included.
Check cookie domain. If your WordPress address and site address differ (e.g., www.example.com vs. example.com), the cookie may not cover both.
Check the Cookie Signing Key. If the signing key is missing or was rotated, existing cookies become invalid. Fetch a new key from the settings page.

Credit Issues

"Credits exhausted" Error

Your monthly free plan credits have been used up. Options:

Wait for monthly reset — credits reset on the 1st of each month (UTC).
Purchase additional credits — available through the XYZ website.
Switch fail behavior — if set to "fail closed," your site is inaccessible to unverified visitors. Consider temporarily switching to "fail open" until credits reset.

Credits Being Used Faster Than Expected

Check the Recent Verifications tab in Settings > Free Plan to see exactly where credits are going:

Failed attempts consume credits — if visitors are frequently failing liveness checks, each failure costs 1 credit.
Tier 2 costs more — document verification attempts cost 2 credits each.
Escalations — if many Tier 1 sessions are being escalated to Tier 2, that's 3+ credits per visitor.
Test mode — verification sessions in test mode also consume credits.

Server / Hosting Issues

OPcache Serving Stale Code

If you update the plugin or MU plugin file but changes don't take effect:

Your server may be caching the compiled PHP. Restart PHP-FPM or clear OPcache.
In Plesk: go to PHP Settings and click "Reset OPcache" or restart the FPM pool.
In cPanel: restart PHP-FPM from the MultiPHP Manager.

File Permissions

The MU plugin file needs to be readable by the web server. Typical permissions:

File: 644 (rw-r--r--)
Directory: 755 (rwxr-xr-x)

If the MU plugin isn't loading, check that the file ownership matches your web server user.

Getting Help

If you've worked through the relevant sections above and are still experiencing issues:

Check the Contextual Help tabs on the plugin settings page (click "Help" in the top-right corner).
Visit support.xyzinc.com for the support forum.
Include the following when reporting an issue: WordPress version, PHP version, any relevant error messages from the browser console or server logs, and the steps to reproduce the problem.

Next Steps