Troubleshooting WordPress Plugin

This guide provides essential information for developers integrating the ALTCHA WordPress Plugin into their website.

Debugging

When accessing the site over localhost or development domains that include a port number, debug mode is automatically activated. In this mode, the Developer Console in your browser will display debugging logs from the ALTCHA Interceptor.

You can also enable debug mode manually on a production site by setting a localStorage variable:

localStorage.setItem("altcha_debug", "1")

Checking if ALTCHA is Verifying

When Invisible Protection is enabled, the ALTCHA widget does not appear during verification, so it might not be immediately clear whether verification is active.

To confirm that ALTCHA is verifying user interactions, inspect the logs in the Developer Console. When a form is being submitted, you should see a message similar to:

ALTCHA Interceptor: Intercepting form submit event POST /example-page/

Alternatively, inspect the network request — it should include an altcha cookie.

API Caching

If you’re using a caching plugin, make sure to exclude the following path:

/wp-json/altcha/v1/challenge

This endpoint generates a new ALTCHA challenge for each verification and must not be cached.

Common Issues

Secure Context (HTTPS) Required

ALTCHA requires a Secure Context (HTTPS) to perform verification. Make sure you access and test your website over HTTPS. localhost is an acceptable exception since browsers treat it as a secure origin.

If you need to test from another device on your local network (for example, a mobile phone), you can either:

• set up HTTPS,
• log in as an admin to bypass verification, or
• whitelist the device’s local IP address to bypass verification.

Submissions Succeed but There Is No Visible Verification

If no ALTCHA widget appears, consider these possible causes:

• You are logged in as an admin user, who is always exempt from verification. View the website as a normal visitor.
• Invisible Protection is enabled. Try disabling it temporarily.
• Your Actions or Paths may be misconfigured. These settings control when verification should occur.

The ALTCHA Widget Appears Randomly on the Page

If the ALTCHA widget appears unexpectedly on your website, it’s likely that another plugin is making AJAX requests in the background.

To identify the cause:

1. Inspect the debug logs (see the Debugging section).
2. Find which action or path triggers the widget.
3. Exclude the action or path in your settings using an exclamation mark (!) before the action name.

You can also learn more about Disabling ALTCHA for Certain Plugins and review known Special Configuration requirements for specific plugins.