Troubleshooting

This page covers the most common issues when running the ALTCHA WordPress plugin, and how to diagnose them.

Debugging

Debug mode turns on automatically when your site is accessed over localhost, or a development domain that includes a port number. In this mode, the browser's developer console shows debugging logs from the ALTCHA Interceptor.

You can also enable it manually on a production site, from the browser console:

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

Checking if ALTCHA is verifying

With Invisible Protection enabled, the widget never appears — so it isn't always obvious whether verification is actually running.

To confirm it, open the developer console and submit a protected form. You should see a log line similar to:

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

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

API caching

If you use a caching plugin or a CDN, exclude this path from caching:

/wp-json/altcha/v1/challenge

This endpoint issues a fresh challenge on every request and must never be cached. Some hosting providers — including WP Engine — may also require excluding the altcha cookie from caching. See API caching for provider-specific notes.

Common issues

Secure context (HTTPS) required

ALTCHA requires a secure context (HTTPS) to perform verification. Make sure you access and test your site over HTTPS — localhost is an accepted exception, since browsers already treat it as secure.

If you need to test from another device on your local network (a phone, for example), you have three options:

Set up HTTPS for that environment.
Log in as an administrator, which bypasses verification automatically.
Whitelist the device's local IP address, so it bypasses verification too.

If the widget renders but verification keeps failing, the challenge endpoint is most likely being blocked, restricted, or modified by a security plugin or firewall.

To fix it:

Whitelist the following endpoint and make sure it's publicly accessible without authentication:
```
/wp-json/altcha/v1/challenge
```
Confirm this endpoint isn't being cached by any caching plugin or CDN — cached responses will break verification. See API caching above.

Next steps

Advanced — hooks, filters, and plugin-specific configuration.
Releases — check whether your issue was already fixed in a newer version.