This page covers common issues encountered during TRACIO integration and their solutions. TRACIO is a managed cloud service, so most issues are client-side (script blocked, cookies, browser privacy features) rather than infrastructure.
The agent script or identification request fails to load, or the browser console shows a CORS error against edge.tracio.ai.
1. Origin not allowlisted for your key
Each public key can be locked to a set of allowed origins. If your site's origin isn't allowlisted, the edge rejects the request (403). Add your origin under Request Filtering in the dashboard, or confirm the key you're using isn't origin-locked to a different site.
2. Ad blocker or CSP blocking the request
Privacy extensions (uBlock Origin, AdBlock) or a strict Content-Security-Policy can block the agent script or its network request. The SDK surfaces this as a blocked error (see Error Handling). To make blocking harder, serve the agent from a first-party subdomain using the scriptUrl / endpoint options.
3. Wrong endpoint / region
Make sure you're pointing at the correct endpoint. When you set region, the SDK talks to edge.us.tracio.ai or edge.eu.tracio.ai; unset, it uses edge.tracio.ai.
Confidence scores are consistently below 0.90 for returning visitors.
1. Cookie not persisting
The _vid_t cookie may not be setting correctly. Check in the browser:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))If the cookie is missing, see the Cookie Not Persisting section below.
2. New workspace
A brand-new workspace has an empty visitor database, so all visitors appear as "new" with a confidence around 0.90. After 24-48 hours, returning visitors are recognized with higher confidence.
3. Incognito/private browsing
In incognito mode, cookies and localStorage are cleared when the session ends. TRACIO falls back to signal-only matching, which has lower confidence (typically 0.85-0.95).
4. Browsers with aggressive anti-fingerprinting
Brave, Firefox (strict mode), and Safari (ITP) modify or block some browser signals. This reduces the signal set available for matching. TRACIO detects these browsers and adjusts confidence accordingly.
Inspect the identification in the dashboard (Visitors / Events), or act on the
webhook delivery, which carries identification.confidence,
identification.incognito, and the bot verdict for each event.
Legitimate human visitors are flagged as bots.
1. Browser extensions modifying navigator properties
Some privacy extensions modify navigator.userAgent, navigator.platform, or other properties. This can trigger the tampering detector but should not trigger bot detection alone.
Check the bot.type field to see which class of detection fired (see Bot Types for the full vocabulary):
| bot.type | Common False Positive Cause | Solution |
|---|---|---|
automation | A testing tool left the browser in automation mode | Disable automation mode outside test runs |
headless | VDI / remote desktop rendering without a real GPU | See "Corporate environments" below |
extension | An automation, proxy, or VPN browser extension is active | Review the extension |
other | A non-specific automation indicator fired | Check reasons (Business+) for the class |
On Business and Enterprise plans, the webhook reasons array names the class of
observation behind the verdict — it is the fastest way to understand a
false positive. See Reason codes.
2. Corporate environments with software rendering
Citrix, VDI, and terminal server environments render without a real GPU, which
resembles a headless runtime. If your users operate in these environments, apply a
softer policy when the webhook shows a headless bot type:
// `event` is the webhook delivery body (/docs/webhooks)if (event.bot?.result === "bot" && event.bot.type === "headless") { // VDI and remote-desktop users render without a real GPU and can trip the // headless classification — consider applying a softer policy for these.}3. Automated testing in production
If your QA team runs Selenium/Playwright tests against production, those will correctly be detected as bots. Use a separate key for test traffic.
The _vid_t cookie disappears between visits, causing every visit to appear as a "new" visitor.
1. Non-HTTPS site
The _vid_t cookie uses the Secure flag and is only set over HTTPS. Ensure your site uses HTTPS.
2. Cross-site loading
TRACIO sets SameSite=Lax on the cookie. If the agent is loaded in a strictly cross-site context, the cookie can be blocked. Serving the agent from a first-party subdomain (via scriptUrl / endpoint) keeps it same-site.
3. Safari ITP
Safari's Intelligent Tracking Prevention (ITP) can cap the lifetime of client-set cookies. TRACIO also issues _vid_t server-side via the Set-Cookie header and mirrors the UID to localStorage, so identity survives even when the cookie is capped.
4. Browser clearing cookies
Some browsers (Brave, Firefox Focus) clear cookies on session end. Users with aggressive privacy settings will always appear as new visitors.
tracio.getResult() takes noticeably longer to resolve than on your other test
devices and networks.
1. Slow network to the edge
Check round-trip latency to your regional edge:
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health2. Collection taking too long
On low-powered devices collection takes longer. Every check that can be slow is bounded by its own timeout, so collection never blocks indefinitely — a check that runs out of time is simply reported as unavailable and the identification proceeds without it.
The identification completes, but confidence is lower than expected on a specific browser or device class.
Not every check can run in every environment: strict CSP, platform restrictions, and browser privacy features all make some of them unavailable. This is expected and handled gracefully — confidence is computed from what was actually collected, which is why hardened browsers legitimately identify with lower confidence than a stock one.
No action is required on your side. If confidence is consistently low across a
large share of your traffic, contact support with a requestId — that is diagnosed
from the server-side record, not from the browser.
If you encounter an issue not covered here:
debug: true SDK optionrequestId of an affected identification