Troubleshooting
Work down the list. Most problems turn up in the first four steps.
Is the script loading? In the browser's network panel,
t.jsmust return 200 asapplication/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, soContent-Encoding: gzipis normal.Is the tracker running at all? It does nothing on
localhost,127.*or[::1]unless the tag hasdata-dev. It also skips pages that are being prerendered.Are events accepted? Look for
POST /_t/e:Status Meaning 204withX-Trail-Accepted: nStored. X-Trail-Rejected: ncounts events in the batch that were skipped as invalid. The valid ones are kept400A 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 POSTandOPTIONSare allowed429Too many requests from one IP. See Rate limit "Unknown site" means
data-sitedoes 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.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.appfor preview deployments). A request with noOriginand noReferer, such as a barecurl, is refused too. See Allowed origins.Accepted, but the charts are empty? Check the environment picker. Events from a host other than the site's domain are tagged
preview,localhostisdevelopment, and the dashboard showsproductionby default. See Environments.Countries empty, or all the same? Make sure your proxy forwards the client IP in
X-Forwarded-Forand is trusted byTRAIL_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 needTRAIL_GEO_DB.Signed out after every restart?
TRAIL_SECRETis 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? Runtrail reset-passwordand restart; see Self-hosting.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 setdata-dnt="off".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
- Configuration lists every setting mentioned above.
- Script tag lists every attribute.