WordPress Plugin Troubleshooting
No signals appearing
Check the connection test first. Go to Logystera → Credentials and click Verify Connection. If it fails:
- Verify your Entity Token and Entity Secret are correct.
- Check that your server can make outbound HTTPS requests to
gateway.logystera.com. - Some shared hosts block outbound HTTP — contact your host to confirm port 443 is open.
If the test passes but no signals appear:
- WP-Cron may not be firing. A page visit only records events to a file on your server; they are sent on a cron schedule (see Events are not arriving below). Trigger cron manually:
bash wp cron run --due-now - Check whether
DISABLE_WP_CRONis set totrueinwp-config.php. If so, your cron must be triggered externally — ensure it runs at least every 60 seconds.
403 Forbidden / signature errors
A 403 response — visible on the Logystera → Ingest Logs page as the last send result, or in your server's error log as a rejected batch — means the gateway received the request but rejected its authentication. The batch is not ingested; the plugin retries later with backoff. The usual causes, most common first:
- Wrong Entity Secret. The request is signed with your Entity Secret, so a mistyped secret — or one regenerated in the dashboard without updating the plugin — makes every batch fail. Re-copy both the Entity Token and Entity Secret from Dashboard → your site → Credentials into Logystera → Credentials, then click Verify Connection.
- A proxy or security plugin altering the request. Some WAFs, firewalls, or optimizers strip or rewrite auth headers or the request body in transit, which invalidates the signature. If batches fail only from behind a proxy, allowlist the plugin's outbound requests to
gateway.logystera.com. - Entity disabled or credentials rotated server-side. If the entity was disabled or its credentials were rotated in the dashboard, re-provision the site from Dashboard → your site → Credentials.
- Large server clock skew. Signed requests are time-sensitive; a server clock that is far off can cause rejections. Confirm the site's server time is correct (NTP-synced).
Billing lock, not credentials: a 403 can also mean the account's subscription has lapsed rather than a credentials problem, and the plugin tells the two apart on its own. When this happens, the Logystera → Status page shows an Ingest: Frozen row (instead of a generic connection error) with an Unfreeze ingest button, and the reason shown on the Ingest Logs page reads "Billing lock" rather than "Auth failed." While frozen, the plugin stops sending entirely — but events keep being captured and buffered locally, so nothing is lost. The freeze lifts on its own the next time the plugin's regular heartbeat finds the account back in good standing, so resolving billing is normally enough; click Unfreeze ingest if you want it to try again immediately instead of waiting for the next heartbeat. Unlike a genuine credentials failure, a billing lock never disables the plugin.
Token vs. secret: a 401 (rather than 403) usually means the Entity Token itself isn't recognized — check the token first. A 403 points at the signature/secret or a request altered in transit. In both cases, Verify Connection is the fastest check: it performs a signed round-trip and reports exactly which step failed.
Events are not arriving
Page visits do not send anything; the plugin records events to a file on your server and sends them in batches. Work through these in order:
- Look at the Status page. Open Logystera → Status and expand Connection Status. If Current State is not Connected, or Backoff / Next Retry show a wait, the plugin is holding events after a failed send; it retries on its own. If you see Ingest: Frozen, see the billing note under 403 Forbidden.
- Check that cron is running. Sending is triggered by WP-Cron (every 5 minutes by default). On a quiet site it only runs when someone loads a page, and if
DISABLE_WP_CRONis set inwp-config.phpit only runs when your host callswp-cron.php. Check that Last Data Sent is within a few minutes of your Flush Interval. To run due cron jobs now:wp cron event run --due-now. To set up a host cron, see Setup and Sending. - Try Send Now. Click Send Now (Flush Queue) on the Status page. A success notice such as "Flush successful. Sent 40 events." means delivery works and the scheduled run is the problem (step 2). An error notice means the send failed; use Verify Connection on the Credentials page.
- Check the buffer. In Connection Status, Queue Size (events) and Live Buffer (with its file count) show what is waiting. A queue that keeps growing while Last Data Sent stays old means nothing is being delivered. On the Debug page (Logystera → Debug), the Buffer Files section lists each buffer file (click Refresh). If Buffer Directory warns that the folder is missing or not writable, fix the permissions on
wp-content/uploads/logystera/or deactivate and reactivate the plugin. - Check that Ingest is on under Event Capture on the Settings page. With Ingest off, events stay local on purpose.
If the buffer fills (50 MB by default) while delivery is stalled, some events are dropped and counted under Dropped Events.
Signals delayed or batchy
This is expected. The plugin sends events on a WP-Cron schedule (default: every 5 minutes). On low-traffic sites, WP-Cron may fire infrequently because it only runs when a visitor loads a page.
To lower latency on low-traffic sites, use a system cron: set DISABLE_WP_CRON to true in wp-config.php and have your host call wp-cron.php every minute (cPanel and Plesk both have a scheduler for this). The steps are in Setup and Sending. You can also reduce the Flush Interval in Logystera → Settings.
Slow gateway or slow page loads
Since 1.0.0 a slow or unreachable gateway cannot hold a visitor's page for long. On servers that finish the response before sending (PHP-FPM, LiteSpeed) the visitor already has the page. On servers that cannot (typically Apache with mod_php) the wait for Logystera at the end of a request is capped at about one second, and one batch; a batch that did not get through is kept and the scheduled send delivers it. After a failed send the plugin backs off (from about 2 minutes, doubling up to 30) and sends nothing on visitors' requests until then.
The plugin shows a notice and stays inactive
On load the plugin checks the PHP version and extensions. PHP below 8.1, or a missing json, openssl or ctype extension, shows an admin notice and the plugin does not load, instead of breaking the site. Upgrade PHP or enable the extension, then reload.
Heartbeat alert firing unexpectedly
The wp_agent_missing_heartbeat alert fires if no heartbeat is received within 30 minutes. Possible causes:
- WP-Cron is disabled or not running.
- The site had downtime during the window.
- Heartbeat delivery failed due to a temporary gateway issue.
The alert auto-resolves the next time a heartbeat is delivered successfully.
High memory usage on shared hosting
The plugin is designed for shared hosting and adds minimal overhead (< 1MB). If you see unusually high memory:
- Disable PHP errors (individual) in PHP warnings under Logystera → Settings → Advanced settings → Event Hooks → Health & Errors — on sites with many PHP warnings the error handler can accumulate events.
- Reduce Batch size in Settings to flush more frequently in smaller payloads.
Duplicate events after migration
If you migrated a WordPress site (moved domain, cloned staging to production), the plugin may have stale credentials. Click Disconnect on the Credentials page, then Connect to Logystera to set up fresh credentials for the new environment. Alternatively, update the Entity Token and Secret manually.
All visitors show as the same few IP addresses
If your site is behind Cloudflare (or another reverse proxy) and logins, failed logins, and brute-force attempts all appear to come from one of a handful of IPs, the agent is recording the proxy's edge address instead of each real visitor. Per-visitor detection then treats unrelated visitors — including attackers — as the same client.
This happens because the agent only trusts X-Forwarded-For / X-Real-IP automatically when REMOTE_ADDR looks like an internal hop (a private/reserved address). Cloudflare connects with a normal public IP, so that check never fires, and the agent falls back to REMOTE_ADDR on purpose — a header a visitor can set themselves isn't safe to trust unless something guarantees it actually came from your proxy.
Fix:
- Lock your origin server so it only accepts connections from Cloudflare's IP ranges. Do this first — without it, a client can bypass Cloudflare, hit your origin directly, and forge the same headers itself.
- Add to
wp-config.php:php define( 'LOGYSTERA_TRUST_PROXY_HEADERS', true ); - If you have more than one proxy hop in front of the site (your own load balancer in front of Cloudflare, for example), also list those proxy IPs so they're peeled off to reach the real client:
php define( 'LOGYSTERA_TRUSTED_PROXIES', [ '203.0.113.10' ] );Exact IPs only — this constant doesn't expand CIDR ranges.
Confirm it worked: open Logystera → Debug and check the Client IP & Proxy card. It shows the resolved client IP, REMOTE_ADDR, the X-Forwarded-For chain with each hop classified (public / private / trusted), and a ✅ or ⚠️ next to the result. If Cloudflare is still misconfigured, the card names the problem and generates the exact wp-config.php line for you.
See Configuration → Visitor IP behind Cloudflare or another proxy for what each constant does.
"Upgrade Required" admin notice
If you see a red banner saying your plugin version is no longer supported:
- Update the Logystera plugin to the version shown in the notice (or later).
- The notice clears automatically after the next successful ingest.
While the notice is active, ingestion is paused — events continue to be collected locally and will be sent once you update. No data is lost.
If you cannot update immediately, events remain buffered locally up to the configured buffer limit.
Checking raw plugin logs
Enable WordPress debug logging and look for [Logystera] prefixed entries:
// wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Log file: wp-content/debug.log