Troubleshooting

URL and routing

`/trust-center/` returns 404

Cause: WordPress is on Plain permalinks. OpenTrust uses rewrite rules for every page; the plain ?p=123 style breaks them all.

Fix: Settings → Permalinks and pick any structure other than Plain. Post name is recommended. Save (the page reloads), and reload your trust center.

OpenTrust surfaces a persistent admin notice when permalinks are plain, with ?opentrust=main query-string fallback links so you can still reach admin screens while it's misconfigured.

Trust center pages still 404 after a permalink change

Cause: rewrite rules were not flushed.

Fix: visit Settings → Permalinks and click Save Changes (no actual change required). This forces a flush. OpenTrust normally flushes automatically after activation and after the endpoint slug changes via an opentrust_flush_rewrite transient, but a third-party plugin may have intervened.

Endpoint slug change did not take effect

Cause: same as above. Flushing the rewrites is the fix.

If the new slug is in the database but every URL still uses the old slug in admin links, hard-refresh the admin screen (Ctrl-F5) so the cached settings JSON in your tab updates.

Branding

Accent colour is showing the WCAG warning

Cause: your hex colour does not clear 4.5:1 contrast against white. OpenTrust will clamp lightness in HSL space until it passes, so the rendered page stays accessible. The "Low contrast" warning is a heads-up, not a blocker.

Fix options:

Pick a darker hex.
Accept the clamp (default behaviour). Buttons and text use OpenTrust's clamped variant; the original hex is not used at all.
Tick Force exact accent to bypass the clamp. The original hex is used everywhere, and your buttons may fail accessibility audits.

Logo or AI avatar will not save

Cause: the file is missing from the media library, or it's an SVG that was uploaded in a format WordPress does not allow by default.

Fix: upload the image via Media → Add New first, then pick it from the OpenTrust settings via the media-uploader. SVG support depends on your WordPress configuration; OpenTrust does not enable SVG uploads itself.

AI chat

"AI chat is not configured" on /ask/

Cause: no API key has been saved for the configured provider.

Fix: OpenTrust → Settings → AI Chat → API key. Paste, save. The chat enables once the key encrypts successfully.

"Saving the API key failed: libsodium not available"

Cause: the host's PHP build does not have libsodium.

libsodium has been bundled with PHP since 7.2 and is present on virtually every modern host. If you're seeing this error, you're either on an unusually old PHP, on a host that has explicitly disabled sodium_*, or running in a hardened container.

Fix: ask your host to enable the sodium extension. Until then, the chat cannot be turned on. The static trust center continues to work.

Chat answers stopped working after a server move

Cause: AUTH_KEY in wp-config.php changed during the move, which invalidates every encrypted secret OpenTrust stores.

Fix: OpenTrust → Settings → AI Chat. Re-enter the API key (and the Turnstile secret if you use it) and save. The chat will work immediately.

This is the intended contract, see Privacy & Security → AUTH_KEY rotation.

"Daily budget exhausted" on /ask/

Cause: visitors have collectively consumed more tokens today than your Daily token budget allows. The chat shows a graceful exhausted state with a button pointing at your contact CTA.

Fix options:

Wait for the daily reset (site-local midnight).
Raise the daily cap in AI Chat → Settings.
Set the cap to 0 to remove the daily ceiling (still bounded by monthly).

Visitor sees "Verification required" repeatedly

Cause: Cloudflare Turnstile is enabled, the visitor passed the challenge, but the bypass transient is not surviving across requests. Common causes are aggressive page caching that strips Set-Cookie headers, or a misconfigured COOKIEPATH / COOKIEDOMAIN.

Fix: exclude /trust-center/ask/ from your page cache. If the issue persists, file a bug with your hosting and cache details.

Citations point at the wrong policy

Cause: rare. Usually means a recently saved policy hasn't been re-summarized yet, so the model's routing index has stale title or summary text.

Fix: OpenTrust → Settings → AI Chat → Summarize sweep. This regenerates _ot_policy_chat_summary for every published policy. Takes a minute or two depending on corpus size.

Auto-summarize is silently failing

Cause: API key invalid, provider rate-limit, Anthropic-only key being used with an OpenAI-only model, etc.

Fix: open OpenTrust → Questions to see whether errors are appearing in the recent activity. Then check the server's PHP error log for opentrust_chat_summarizer entries; the summarizer logs underlying provider errors when summary generation fails. Re-saving the API key (or switching to a working provider) usually fixes it.

The chat itself falls back to the policy excerpt as the routing hint when no summary is available, so a temporarily broken summarizer doesn't break the chat.

Content

Subprocessor catalog typeahead is not appearing

Cause: you're on the Edit screen, not the Add-New screen. The typeahead is intentionally only on the Add-New screen so editing existing entries doesn't fight your typed values.

Fix: add a new subprocessor via OpenTrust → Subprocessors → Add New. The catalog typeahead will be active.

Bundled FAQs reappear after I delete them

Cause: if no FAQs exist at all and the opentrust_faqs_seeded flag is not set, OpenTrust seeds the default catalog on the next page load. This only happens once per fresh install, but a database that's been wiped between activations can re-trigger it.

Fix: leave at least one FAQ in place (even draft) and the seeder won't run. The flag itself can be checked in Tools → Database if you have a query plugin: opentrust_faqs_seeded should be 1.

WordPress version, PHP version, OpenTrust version.
Whether AI chat is enabled and which provider.
The exact admin notice or visitor-side error text.
Anything in the WP error log with opentrust or the provider name when WP_DEBUG_LOG is enabled.