Skip to main content

When Something Is Not Arriving

Every entry here is a real failure that has happened, with the symptom first — because the symptom is what you have, and the cause is what you are looking for.

Nothing at all is arriving​

Press "Check now" in Settings → Connection first. StorePilot fetches the site's own address the way a visitor would and reports what it finds on the page. It answers the question the dashboard cannot, because everything else the platform knows comes from requests that arrived:

  • The tag is there and carries this site's key. The install is fine, and the cause is after collection rather than before it — consent, an excluded URL, or genuinely no traffic.
  • The tag is there and carries a different site's key. This is the failure that looks like nothing at all: the snippet works perfectly and stores everything under the other site. Nothing on either dashboard says so, and it is why this check exists.
  • No tag was found. The snippet or the plugin is not on the page that was checked.
  • The page could not be checked. A redirect, a timeout, or an address that resolves somewhere private. This is a statement about the check, never about the installation.

Nothing is stored from that page and no credentials are sent — it reads the public HTML and keeps a few booleans.

The banner across the dashboard says why the site is silent, and it says only what was observed. "Nothing has ever reached us" and "connected, but nothing stored yet" are different sentences because they send you to different places; a refused origin is named with the exact address that was turned away, and a browser opt-out is reported as a count rather than blamed for the silence.

The site says "Nothing received yet"​

  • The plugin is installed but no API key is saved. Settings → StorePilot in WordPress. The key is the one labelled API key in Settings → Connection, not the public key.
  • The key was rotated. Rotating the API key takes the site offline until the new value is pasted into the plugin. That is deliberate — the old key stops authorising ingest immediately — but nothing on the site announces it.
  • The script tag has the wrong key. The snippet uses the public key. Pasting the API key into a <script> tag publishes a credential and, because the two are different columns, does not work either.
  • The script tag is on a domain the site does not know about. A scriptless install is accepted on the strength of the browser's Origin header, matched against the site's domain, its www. twin, and anything in Allowed origins. A staging host, a preview URL or a second brand domain has to be listed there. Settings shows the last origin that was refused and when — if that field is filled in, this is your problem.

Errors stopped arriving, everything else works​

A payload was rejected as malformed. The API validates strictly and refuses unknown fields. When the WordPress proxy sees that, it reports rejected_key in the site's admin notice — distinct from unreachable (the platform could not be reached) and refused (the key was not accepted). Those three used to read as one message, "Platform unavailable", which sent everybody looking at the wrong thing.

If you see rejected_key, the plugin and the platform disagree about a payload shape. Update the plugin.

The wrong country for every visitor, or one visitor doing everything​

The site is behind Cloudflare or another CDN and has not said so. From plugin 1.7.0 the visitor's address is taken from the socket, not from a header — because CF-Connecting-IP and X-Forwarded-For are written by whoever sends the request, and believing them meant anybody could forge an address per request, defeat the rate limits and put a chosen IP on every stored lead.

Behind a CDN, the socket address IS the CDN, so every visitor looks like one machine in one country. Declare the proxy in wp-config.php:

define( 'STOREPILOT_TRUSTED_PROXY', '173.245.48.0/20, 103.21.244.0/22' );

StorePilot's Settings screen raises a notice when it sees a proxy header arriving and no trusted proxy declared, so you should not have to find this on your own.

A script tag change has not taken effect​

Give it a minute — literally. The loader at /sp?k=… is cached for 60 seconds and the bundles it names are immutable and cached forever. That is the arrangement that lets a collector fix reach every site within a minute.

If it has been much longer than a minute, something between you and us is caching the loader itself. That is why the canonical path has no file extension: a CDN in front of an earlier deployment classified /sp.js as a static asset and served one body for 55 minutes against our max-age=60. /sp.js still works forever, but a pasted /sp.js tag is the one that can be over-cached. Settings prints the current snippet; use that.

Recordings are not appearing​

  • Consent is required and the page is not asserting it. With Require consent on, nothing is stored until the page signals it. That gate is the point, but it is easy to turn on and forget.
  • The page is on the excluded list. Exclusions default to suppressing recordings only — a shop that excludes /checkout/* almost always means "do not film my checkout" rather than "stop counting its pageviews".
  • The visitor sent Global Privacy Control. Sec-GPC: 1 refuses collection unconditionally, with no per-site override — under the CPRA it is a binding request, not a preference. DNT: 1 is not a signal and changes nothing; if your own browser has Do Not Track switched on, that is no longer why your visits are missing.
  • The monthly recording allowance is used up. Errors and leads keep flowing past the limit; recordings and analytics do not. The Plans screen says which allowance was reached.

A heatmap has clicks but no background picture​

That is a supported state, not a fault. The background is a PNG the platform renders from a stored session recording, and it needs footage to exist first — a fresh install has clicks before it has anything to render from. The overlay keeps the scroll scale, the element ranking and the vertical band chart in the meantime.

If it never appears, the deployment may have no rendering support (it is optional and requires Chromium). Nothing else about heatmaps is affected.

Notification emails or webhooks never arrive​

Settings → Notifications has a Test button next to each channel. It sends one real message through the same sender with the same stored credential, and reports what happened — including "not configured", which is a third state and not a failure. A 404 from a deleted Slack hook comes back as a failed delivery with the detail, rather than as silence.

The test reads the saved value. An edit in the field above it that has not been saved is not what gets tested, and the button says so.

An address change did not take effect​

Changing the email you sign in with is two steps: the new address is parked until you open the confirmation link sent to it. Until then you sign in with the old one, and the profile screen says so. That exists because a typo would otherwise leave the account reachable only at an address you have never seen — and the way back into a locked account is a link sent to exactly that address.