Troubleshooting

Troubleshooting

If something isn't working, walk this list top-to-bottom — issues are ordered from most- to least-common.

The pixel isn't sending events

Symptoms: EVENTS · 24H on the dashboard stays at 0 after you install the pixel. DevTools → Network shows no POSTs to /v1/browser/events.

1. Confirm the script loaded. Open DevTools → Sources and look for pixel.js under the tracklayer-ingestion.sublime.workers.dev origin. If it's missing, your <script src> URL is wrong or Content-Security-Policy is blocking it.

2. Check for CSP violations. DevTools → Console for messages like Refused to load the script 'https://tracklayer-ingestion.sublime.workers.dev/v1/pixel.js' because it violates the following Content Security Policy directive. If present, add the host to your script-src:

   Copy

   script-src 'self' https://tracklayer-ingestion.sublime.workers.dev;
   connect-src 'self' https://tracklayer-ingestion.sublime.workers.dev;
   

   Scroll code horizontally when needed

3. Verify data-merchant is set. The pixel console-warns if the attribute is missing:

   Copy

   [tracklayer] missing data-merchant on script tag
   

   Scroll code horizontally when needed

   Copy the exact UUID from Settings → Account, paste into the attribute, reload.

4. Check that events aren't being dropped as bot traffic. The server returns 202 {"ok":true,"dropped":"bot"} if the User-Agent looks bot-like (headless Chrome without --user-data-dir, common scraper signatures). Test from a normal browser window.

Events hit ingest but show no_platforms in the stream

Symptoms: Events list in the dashboard shows no_platforms / FANOUT 0/0.

Your merchant hasn't connected any CAPI destinations yet. Open Platforms and connect at least one. Events already ingested stay as no_platforms permanently (the consumer only attempts delivery once per event). Future events use the new platform list.

A platform is DROPPED or DEGRADED

Symptoms: Platform card shows a red or amber pill.

1. Click the platform to open its detail drawer.
2. Check Validation Issues — the top row is the most-common reject reason. Typical culprits:
   • Missing user_data.email (Meta, TikTok, Snapchat)
   • Missing user_data.phone (SMS retargeters)
   • Missing order_id for purchase events (attribution platforms)
   • Missing items[] for catalog-matched platforms (Criteo, Pinterest)
3. Add the missing field to your pixel payload or server-side track call. Existing events stay failed but new events will deliver.

Stripe checkout throws 502 "Rotate STRIPE_SECRET_KEY"

Symptoms: Upgrade button on Settings → Billing redirects to an error.

The worker has a STRIPE_SECRET_KEY set, but the value is a placeholder or expired. In the Cloudflare dashboard (or via wrangler secret put):

cd workers/api
wrangler secret put STRIPE_SECRET_KEY
# paste your sk_test_... or sk_live_... at the prompt
wrangler secret put STRIPE_WEBHOOK_SECRET
# paste the whsec_... from Stripe → Developers → Webhooks

No redeploy required — secret rotation takes effect on the next request.

Rate limited at /v1/browser/events

Symptoms: 429 responses in DevTools → Network.

The browser endpoint limits 30 events / 60s per (merchant_id, client IP). If your store legitimately fires more than that, switch to the server-side path:

curl -X POST https://tracklayer-ingestion.sublime.workers.dev/v1/events \
  -H "Authorization: Bearer tl_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{...}'

Server-side /v1/events has a much higher limit (100 events/sec per API key).

Replayed events don't appear in the events list

Symptoms: POST /v1/events/:id/replay returns 200 with a new event_id, but the new event never shows up.

Check that the new event_id follows the .replay. suffix pattern. Search for it in the Events page with the full ID. If it still doesn't appear after ~8 seconds:

1. The event_time on the original was malformed (year out of range) — replays inherit the original event_time. Fix: re-fire the original with a correct epoch-seconds value.
2. The consumer worker version is older than the API worker version. Trigger a redeploy:

   Copy

   cd workers/consumer
   wrangler deploy

   Scroll code horizontally when needed

Rules aren't being applied

Symptoms: A rule is saved + enabled, but events still fan out to all platforms.

1. Confirm the rule's event_name exactly matches what the classifier produces. The pixel normalizes AddToCart → add_to_cart on ingest; your rule must match the normalized name.
2. Confirm enabled: true on the rule (check the badge on the Rules page).
3. Confirm the consumer worker version is post-283d436 — earlier deploys didn't read the rules table. wrangler deployments list shows current version.
4. Check Supabase directly — if the routing_rules table doesn't exist, rules UI shows an amber "MIGRATION PENDING" banner. Run supabase db push or apply 20260420_005_routing_rules.sql.

My /rules page shows MIGRATION PENDING

The routing_rules table hasn't been created yet. From the repo root:

supabase db push

Or via the Supabase Management API if you have a token:

curl -X POST \
  "https://api.supabase.com/v1/projects/YOUR_PROJECT_REF/database/query" \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @supabase/migrations/20260420_005_routing_rules.sql

Still stuck?

Open the AI assistant — Cmd+K → ? — and describe what you're seeing. It has read access to your events, platforms, and health metrics and can usually identify the failure mode directly.

For things the assistant can't solve, email support@tracklayer.io or open an issue on github.com/DigitalSoftDistribution/tracklayer.