> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traceten.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix the most common Traceten snippet installation problems.

## The dashboard verification panel stays gray

**The snippet is installed but events aren't arriving.**

Work through these checks in order:

1. **Did you visit the correct domain?** The snippet's `data-site` key is tied to a specific site in your dashboard. If you're testing on `localhost` or a staging subdomain, make sure you're viewing the right site in the dashboard.

2. **Is the snippet tag actually in the page HTML?** Right-click the page, select **View Page Source**, and search for `traceten`. If you don't find it, the snippet was not saved or the page is cached. Clear your CDN cache and try again.

3. **Is the page served from cache?** If your site uses a CDN or caching layer (Cloudflare, Fastly, WP Rocket), the cached version may pre-date your install. Purge the cache and reload.

4. **Is an ad blocker running?** Ad blockers can block requests to `ingest.traceten.com`. Disable your ad blocker or test in a private/incognito window with extensions disabled.

5. **Is there a Content Security Policy blocking the script?** See [CSP issues](#content-security-policy-csp-blocking-the-snippet) below.

***

## Ad blockers block the snippet

Ad blockers and privacy extensions (uBlock Origin, Privacy Badger, Brave's shields) may block the snippet or the event POST. This is expected behavior for end users and does not indicate an installation problem.

When testing your own installation, disable your ad blocker or use a browser profile without extensions. In production, the fraction of visitors with ad blockers enabled will simply not be tracked. This is a known limitation of any client-side analytics.

There is no workaround for this that does not violate the user's explicit preference. We do not recommend proxying the ingestion endpoint to bypass ad blockers.

***

## Content Security Policy (CSP) blocking the snippet

If your site sets a `Content-Security-Policy` header, it must explicitly allow the Traceten script source and connect destination.

Add these directives:

```
Content-Security-Policy:
  script-src 'self' https://cdn.traceten.com;
  connect-src 'self' https://ingest.traceten.com;
```

If you use a hash-based or nonce-based `script-src`, you'll need to add a nonce to the script tag or switch to the host-based allowlist above.

To confirm whether CSP is the issue: open DevTools, go to the **Console** tab, and look for a message like `Refused to load the script 'https://cdn.traceten.com/tt.min.js' because it violates the following Content Security Policy directive`.

***

## Single-page app navigation not tracked

The snippet fires one pageview when it first loads. It does not automatically detect client-side navigations (React Router, Next.js, Vue Router, etc.), so route changes in a single-page app must fire a pageview manually:

```javascript theme={null}
// After each route change in your SPA
if (window.traceten) {
  window.traceten("pageview");
}
```

For React Router:

```typescript theme={null}
import { useEffect, useRef } from "react";
import { useLocation } from "react-router-dom";

function useTraceten() {
  const location = useLocation();
  const isFirstRender = useRef(true);
  useEffect(() => {
    // The snippet already tracks the initial load; only fire on navigations.
    if (isFirstRender.current) {
      isFirstRender.current = false;
      return;
    }
    if (typeof window.traceten === "function") {
      window.traceten("pageview");
    }
  }, [location.pathname]);
}
```

For Next.js, see the [Next.js guide](/install/nextjs#single-page-application-navigation). The full method reference is in the [browser API reference](/sdks/browser).

***

## The snippet slows down my page

The snippet is designed to have zero impact on page performance:

* It loads with `async`, so it never blocks the parser.
* All detection work runs in `requestIdleCallback` (or a `setTimeout(0)` fallback), so it yields to user interactions.
* The script is under 10KB gzipped. It adds less than 5ms to a typical page load on a slow connection.
* There is one POST request to `ingest.traceten.com` per pageview. It is non-blocking.

If you're seeing performance regressions after install, check whether you removed the `async` attribute from the script tag. Without `async`, the browser pauses HTML parsing to load the script synchronously.

***

## I see duplicate events in the dashboard

Duplicate events usually mean the snippet tag appears twice in the page HTML. Search your page source for `traceten` to confirm.

Common causes:

* The snippet was added to both a parent theme and a plugin (WordPress).
* The snippet was added to a global layout and also to individual page templates.
* Two snippets with different `data-site` keys on the same page.

Remove duplicates until the tag appears exactly once per page.

***

## Visitors are counted twice, or conversions on another subdomain are not attributed

If your funnel spans subdomains (say a visitor lands on `www.example.com` and converts on `checkout.example.com`) and the conversion arrives with no originating visit, the cause is almost always cookie scope.

Without `data-cookie-domain`, Traceten's identity cookies are **host-only**, so a cookie set on `www.example.com` is never sent to `checkout.example.com`. The visitor is re-identified as brand new on the second host and the two sessions are never joined.

Check the tag on each subdomain against the one on your site's install page. Either one of them is missing the attribute or carries a different value (typed by hand, copied from an older install, or trimmed by a template), or the site has no cookie domain confirmed at all, which is the default for every site until you set one under **Sites → Settings → Cookies**. Settings shows the current state and, if nothing is confirmed yet, a suggested value to review.

Symptoms:

* Visitor counts higher than expected, roughly doubled across a two-subdomain funnel.
* Conversions attributed to `direct` when the visitor demonstrably arrived from an AI source.
* Session counts that do not fall when a visitor moves between subdomains.

The fix is the same tag, with the same `data-cookie-domain`, on **every** page that loads the snippet:

```html theme={null}
<script
  async
  src="https://cdn.traceten.com/tt.min.js"
  data-site="ttid_7Rb4TrC1dTbnD8w3s1TS12"
  data-cookie-domain="example.com"
></script>
```

To confirm it is working, open DevTools → Application → Cookies on each subdomain. The cookie whose name starts with `_traceten_vid` should show the same value on both, with `Domain` set to `.example.com` rather than the specific host. A broadened cookie carries your site key in its name (`_traceten_vid_7Rb4TrC1`); a host-only one is just `_traceten_vid`, and seeing that on a subdomain is the symptom itself.

See [cross-subdomain tracking](/sdks/browser#cross-subdomain-tracking-data-cookie-domain) for the full behavior, including hosted checkouts on a genuinely different domain, which cookies cannot cover.

***

## The site key looks wrong in the snippet

The `data-site` attribute must match exactly what the dashboard shows for your site. Site keys look like `ttid_7Rb4TrC1dTbnD8w3s1TS12`: the fixed `ttid_` prefix followed by 22 letters and digits. They are case-sensitive: copy the key exactly as the dashboard shows it, because a key with changed capitalization is rejected by the collector and no events are recorded.

If you copied the tag from the dashboard and it already had the correct key, but you modified it, regenerate the snippet from the dashboard's install page.

***

## Still stuck?

If none of the above resolves your issue, collect the following information before reaching out:

1. The URL of the page where the snippet is installed
2. A screenshot of the Network tab in DevTools showing the `tt.min.js` request (or its absence)
3. Any console errors related to `traceten`
4. Your browser and ad blocker setup

Then open a support ticket from the dashboard.