Skip to content

Troubleshooting ​

Work down the list. Most problems turn up in the first four steps.

  1. Is the script loading? In the browser's network panel, t.js must return 200 as application/javascript. A 404 usually means the /_t/* rewrite is missing or points at the wrong host. The tracker files are served gzipped when the browser accepts it, so Content-Encoding: gzip is normal.

  2. Is the tracker running at all? It does nothing on localhost, 127.* or [::1] unless the tag has data-dev. It also skips pages that are being prerendered.

  3. Are events accepted? Look for POST /_t/e:

    StatusMeaning
    204 with X-Trail-Accepted: nStored. X-Trail-Rejected: n counts events in the batch that were skipped as invalid. The valid ones are kept
    400A batch with no valid events, an unknown site id, or a batch with mixed sites. The response body says which
    403The page's host is not allowed for this site. The body is empty. See the next step
    413Body over 64 KB
    405Wrong method. Only POST and OPTIONS are allowed
    429Too many requests from one IP. See Rate limit

    "Unknown site" means data-site does not match a site id. Open Settings in the dashboard to see the ids, or add the site. The server log says "no sites yet" at startup when none exist.

  4. A 403 on /_t/e? The page is on a host the site does not allow. Open the site's Install panel in Settings: its live check warns when events were rejected for their origin. Add the host under Allowed origins (for example *.vercel.app for preview deployments). A request with no Origin and no Referer, such as a bare curl, is refused too. See Allowed origins.

  5. Accepted, but the charts are empty? Check the environment picker. Events from a host other than the site's domain are tagged preview, localhost is development, and the dashboard shows production by default. See Environments.

  6. Countries empty, or all the same? Make sure your proxy forwards the client IP in X-Forwarded-For and is trusted by TRAIL_TRUSTED_PROXIES (see Client IP and proxies); otherwise every visit looks like it comes from the proxy. Settings → Config shows which geo database is in use. Region and city need TRAIL_GEO_DB.

  7. Signed out after every restart? TRAIL_SECRET is set to a value that changes on each start. Unset it (Trail then keeps its own key in the database) or fix it to one value of 32 or more characters. Lost the generated password? Run trail reset-password and restart; see Self-hosting.

  8. Some visits are missing? Requests that look automated are stored with a bot flag and left out of every report. That includes browsers driven by Playwright, Puppeteer or Selenium, which set navigator.webdriver. Visitors who send Do Not Track or Global Privacy Control are not tracked unless you set data-dnt="off".

  9. Still stuck? Run the server in the foreground, watch its log while you load the page, and open an issue with what you saw.

Next ​