# 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:

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

### Checking if ALTCHA is verifying

With [Invisible Protection](/docs/wordpress/features/#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](/docs/wordpress/advanced/#api-caching) for provider-specific notes.

## Common issues

### Secure context (HTTPS) required

ALTCHA requires a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (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.

### Widget displays, but verification fails

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:

1. Whitelist the following endpoint and make sure it's publicly accessible without authentication:

```
/wp-json/altcha/v1/challenge
```

2. Confirm this endpoint isn't being cached by any caching plugin or CDN — cached responses will break verification. See [API caching](#api-caching) above.

## Next steps

- **[Advanced](/docs/wordpress/advanced/)** — hooks, filters, and plugin-specific configuration.
- **[Releases](/docs/wordpress/releases/)** — check whether your issue was already fixed in a newer version.