Troubleshooting

Each entry starts from what you see. For every status and reason code, see Errors.

The verdict fetch always returns 404

• The page and the backend use different sessionRef values. Log the value you pass to start() and the value you fetch, and compare them.
• The fetch runs more than 2 minutes after the collection. Fetch right after ready() resolves.
• The collection never reached Octet. Check the browser console for a rejected ready(), and look up its status in Errors.
• The edge's license and your read token belong to different licenses. A read token reads only the verdicts that arrived under its own license.

The browser console shows a CORS error

The page's origin isn't in the edge's ALLOWED_ORIGIN. Add the exact origin, including the scheme and any port, for example https://www.example.com, and restart the edge.

Every session gets 401 or 403 from the edge

Octet refused your license token, your edge's client certificate or its signature. The reason in the edge's response, and in the edge's log, says which. See Reasons Octet gives your edge.

Every session gets 400 with unsealed_bundle

The page serves a collector older than v1.3.0, which Octet no longer accepts. Download the current octet-collector.js and its octet-collector.js.sri, and serve both from your origin. See Embed the Collector.

Honest users get medium or high

Check that nothing terminates TCP or TLS in front of the edge. A proxy, application load balancer or CDN in front of the edge makes verdicts wrong for every user. See Deploy the Edge.

If the edge is set up correctly and a specific honest session still gets medium or high, send its sessionRef and time to developer@octetproof.com.

Every verdict has the same country, the one where my servers are

Something in front of the edge is replacing the user's IP address with its own. The edge reads the user's IP address from the connection itself, not from forwarded headers. Remove the device, or switch it to layer 4 passthrough.

VPN sessions come back as none

• Check that the page runs in full mode, the default. lite and passive give Octet less evidence.
• Check that your CSP allows the hosts for your mode and worker-src blob:. See Network and CSP.
• Octet does not flag every masked session.

ready() is slow

• Call start() at page load, not at the moment of action, so that the collection is done by the time the user acts.
• On some connections, ready() can take up to about 4.5 seconds in full mode, and up to about 3 seconds in lite mode. Allow for this in any timeout you set.

The collector script doesn't load

• Serve octet-collector.js from your own origin. A src that points at the GitHub release URL won't load.
• Check that the integrity value is the exact contents of octet-collector.js.sri from the same release as the script. A mismatch blocks the script.
• Check that your script-src allows the path you serve it from.

The edge log says plain HTTP

EDGE_TLS_CERT_FILE or EDGE_TLS_KEY_FILE is unset, so the edge is serving HTTP. Set both and restart. See Edge Configuration.

The edge doesn't start

The edge refuses to start without its client certificate and key, EDGE_CLIENT_CERT_FILE and EDGE_CLIENT_KEY_FILE, or with an OCTET_URL that isn't https://. Run sudo journalctl -u octet-edge -n 20. The last line names what is missing, for example mTLS to octet is required, set EDGE_CLIENT_CERT_FILE, EDGE_CLIENT_KEY_FILE. To get the files, see Deploy the Edge.

The edge log warns that EDGE_SIGNING_KEY is unset

The edge is forwarding sessions without a signature. Create a signing key, set it as EDGE_SIGNING_KEY, restart the edge and register the key in the portal. See Deploy the Edge.

Our auditor wants to check our verdicts

Give the auditor your stored tokens, the Octet keys you kept, and the check in Keep Verdicts for Audit. The auditor needs no Octet account.

Still stuck

Email developer@octetproof.com with the sessionRef, the time of the request, and the status and reason code you saw. Never send a license token, read token or private key.