Nonce Failure Explainer

Description

“Security check failed” is an outcome, not a diagnosis. It does not tell you whether the nonce
field was missing, the action string differed, the session ended, a cached page served a stale
value, or the nonce simply expired.

Nonce Failure Explainer records every failed nonce check and states the most likely cause, along
with the specific thing to check next.

What it records

For each failure:

• The most likely cause, with an explicit confidence level
• A concrete next check to run
• The nonce action string
• The request type (ajax, rest, admin, admin-post, cron, cli, frontend), method, and path
• A best-effort guess at which plugin or theme ran the check
• Whether the user was logged in

What it never records

• The nonce value itself
• Authentication cookies or session tokens
• Passwords, API keys, or any request body
• Query strings, which routinely carry one-time tokens

Function arguments are excluded from the stack trace capture, so sensitive values are never
even loaded into memory during attribution.

Causes it distinguishes

• No nonce was submitted — the field or query argument never reached the server. Confirmed,
  not inferred.
• The session ended — an auth cookie arrived but no longer resolves to a user.
• A cached page served a stale nonce — detected when an anonymous request fails while a known
  caching layer is active.
• No session token — the user is logged in but has no session for the nonce to key against.
• Expired or mismatched action — everything needed was present, so the value itself did not
  match.

Design

Read-only. The plugin observes and explains; it never alters a request, extends a nonce lifetime,
or changes site behaviour in any way. Storage is a single non-autoloaded option capped at 200
events with a seven-day expiry, so it cannot grow unbounded on a busy site.

Nothing is sent anywhere. There is no external service, no telemetry, and no phone-home.