Troubleshooting
Every console message the SDK can produce, what it means, and the traps that cost the most time.
Everything the SDK tells you goes to the browser console, prefixed with [TrackBee]. Filter on that and you will see all of it.
Nothing is arriving
Work down this list.
1. Did the SDK start? Look for this on load, with whichever version is live in place of <version>:
[TrackBee] Tracking SDK v<version> — loadedNo line, and no [TrackBee] error either, means the file never ran. Check the network tab for trackbee-tracking-sdk.min.js. A blocked or failed request is almost always an ad blocker or a content security policy. If your site sends CSP headers, cdn.trackbee.ai needs to be allowed in script-src, and gateway.trackbee.ai in connect-src.
2. Is the configuration right? A [TrackBee] error on load means the script loaded but refused to start. See configuration errors.
3. Did the event validate? A dropped event always says so. See rejected events.
4. Did the request fail? See requests that could not be sent.
5. Is the key right? A wrong but well-formed data-pak produces no error anywhere. The SDK does not read the response, so a rejected key looks exactly like a successful send. If everything above is clean and the data still is not showing up, check the key with your TrackBee contact.
Configuration errors
These stop the SDK entirely. No events, and window.trackbee stays the stub.
| Message | Fix |
|---|---|
No script tag with data-pak attribute found. TrackBee not initialized. | The script tag is missing, or has no data-pak. |
data-pak attribute is empty. TrackBee not initialized. | data-pak is there but has no value. |
data-identity-mode attribute is empty. TrackBee not initialized. | data-identity-mode is missing or has no value. It is required and has no default. |
data-identity-mode value must be either 'url' or 'internal', received: ... | Only those two values work. |
The tracking SDK has already been loaded. You should only include it once! | See the script is on the page twice. |
The visitor ID is not a UUID
[TrackBee] The visitor id in the _t_i URL parameter must be a UUID. Received: "..."
[TrackBee] The visitor id in local storage under _t_i must be a UUID. Received: "..."Your events are still sent and still stored. What TrackBee cannot do is keep this visitor's attribution, so a conversion they make later is not matched back to the ad that brought them in.
| Where it came from | What to do |
|---|---|
The _t_i URL parameter, in url identity mode | Fix whatever builds those links so it passes a UUID. |
Local storage, in internal mode | Something other than the SDK wrote to the _t_i key. Find it, or clear the key and reload to get a fresh ID. |
Rejected events
| Message | Meaning |
|---|---|
Unknown event type: "...". Known events: page_view, product_view, add_to_cart, checkout_started, payment_info_submitted, checkout_completed | The event name is not one of the six. |
track("...") did not send the event. Missing required fields: ... | A required field was absent, null or undefined. |
track("...") did not send the event. Invalid fields: ... | A value had the wrong type or format. The message names the field, what was expected, and what you passed. |
the value passed to 'cartToken' must be a non-empty string. Received: ... | Cart token takes a non-empty string. |
the object passed to 'setConsent' must ... | See consent. setConsent is the internal name for trackbee.consent. |
In every case the event is dropped. Nothing partial is sent.
Requests that could not be sent
[TrackBee] Could not send the "product_viewed" event to https://...: TypeError: Failed to fetchThe event was built and the request was attempted, but the browser could not complete it. Usually an ad blocker, a content security policy, or the visitor being offline.
Failed requests are not retried and not queued. That event is gone.
Note the name in the message is the internal event name, which is not always the one you passed:
| You call | It reports |
|---|---|
page_view | page_viewed |
product_view | product_viewed |
add_to_cart | product_added_to_cart |
The other three match.
Things are counted twice
The script is on the page twice
[TrackBee] The tracking SDK has already been loaded. You should only include it once!The second copy refuses to start, so you are not double counting, but find and remove it. This usually means the snippet is in both a layout and a template, or a theme and a tag manager.
Page views are doubled on a single page app
Your router fires on initial mount as well as on route change, and the page itself also sends one. Send the page view from one place only. See sending the page view.
Orders are doubled
The confirmation page was reloaded or revisited. Guard the event with the order ID. See send it once.
Some events arrive, others do not
Two usual causes.
A saved reference to the global. var tb = window.trackbee grabbed before the SDK started keeps pointing at the stub, and the SDK does not drain it a second time. Those calls go nowhere, silently. Always call trackbee.track(...) directly.
A misspelled field. The event sends without that field, and nothing warns you. Check your field names against the page for that event.
Fields are missing from an event
Fields the event does not recognize are dropped with no message. Check the spelling, and check it against the right event: image_url works on product_view but not on add_to_cart, for example.
Line items are the common one. They do not inherit the currency you set at the checkout level, so a line without its own currency arrives without one.
Messages about storage
[TrackBee] Error reading key _t_i from local storage: ...The browser is blocking local storage, through private browsing or a site setting. The SDK keeps working, but it cannot keep a visitor ID between page loads, so each page looks like a new visitor. Nothing to fix on your side.
Browser support
Current versions of every major browser, plus Chrome 109, the last version that runs on Windows 7 and 8.
Internet Explorer, Opera Mini, UC Browser, QQ Browser and KaiOS are not supported. On those, the script may not run at all.
Still stuck
Collect the [TrackBee] console output and the failing request from the network tab, and send both to your TrackBee contact.