Skip to main content

FAQ & Troubleshooting

In one sentence

Indexed by what you actually see — each entry gives the fix.

Verdicts​

Confidence is consistently low​

Most often the edge isn't the connection-terminating hop — a TLS-terminating CDN or load balancer is sitting in front of it, so the connection-level timing signal reflects that intermediary instead of the browser. Preserve termination (see Cloud LB / CDN) or run the edge closer to the edge. If you can't, that's supported — confidence is just lower. Coordinate your topology with Octet.

The verdict fetch returns { "status": "pending" } (HTTP 404)​

The verdict isn't ready, usually because:

  • The browser is still collecting — add ?waitMs=2000 to long-poll, or fetch slightly later.
  • The sessionRef doesn't match the one the collector used — make sure the same token is minted by your backend, passed to verify(), and used in the fetch.
  • The browser never reached your edge (verify() failed) — check the browser console and that apiUrl resolves to your edge.

Verdicts are held only briefly after collection, so fetch reasonably soon after the page view.

Collector​

npm install @octetproof/collector fails with 401 / 403​

The package is on GitHub Packages, which requires authentication even for reads. Create a token with the read:packages scope and configure .npmrc:

@octetproof:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

See Collector package.

The WebSocket (latency channel) fails to connect​

  • Make sure the page is served over HTTPS — the channel uses wss.
  • If the edge is behind a reverse proxy, confirm the proxy passes the WebSocket upgrade headers for /v1/ws (see nginx / Caddy).
  • If you set wsUrl explicitly, confirm it points at the edge's /v1/ws.

A failed latency channel isn't fatal — collection continues — but it weakens the result.

CORS errors in the browser console​

Serve the collector and expose the edge under the same origin as your page (e.g. yourapp.com/octet). If the edge is on a different subdomain, allow that origin. See Embed the Collector.

Edge​

Octet rejects the license key (unlicensed)​

Octet rejected the edge's license key. Confirm LICENSE is set on the edge and matches the key Octet issued you. Through the edge this surfaces as an empty verdict (no country); a direct call to Octet returns HTTP 401 unlicensed. (In local dev, when no key gate is configured, this check is open.) See Licensing.

The edge returns 502 octet_unreachable​

The edge couldn't reach Octet. Check OCTET_URL and outbound network/firewall. (If you've enabled the planned mutual TLS, also confirm OCTET_CA_FILE, EDGE_CLIENT_CERT_FILE, and EDGE_CLIENT_KEY_FILE point at valid files.) See Edge Configuration.

The verdict fetch returns 401 unauthorized​

Your backend's x-octet-partner-key is missing or wrong. It's a different credential from the edge's license key — see Licensing.

Still stuck?​

Reach out to Octet with your sessionRef and the timestamps involved. Don't include any keys or certificates in support requests.