Troubleshooting

The few things that actually go wrong, and how to confirm each one. Start with surfil doctor - it answers most of these in one command.

No receipt after a session

The most common one - usually the session was too small to measure, not a failure. Walk the first-run checks: confirm the device is linked, the adapter is wired, and surfil mind stats shows facts. Then run a normal working session and surfil audit.

Agent traffic isn't being intercepted

1. surfil doctor - is the agent listed with an active adapter?
2. If missing, re-run curl -fsSL https://surfil.com/install.sh | sh so its adapter is wired.
3. Confirm the agent's base URL points at the local runtime - requests bypassing the single interception point produce no facts.

Cache hit-rate dropped after installing

This should never happen - interception is byte-exact specifically to preserve provider prefix caches. If cache hits fell, treat it as a bug, not expected behavior: capture surfil doctor output and report it. Byte-exactness is asserted in CI, so a regression here is a real defect.

A device is suddenly refused

A refused device is almost always a revoked one - revocation is fail-closed and takes effect on the next call. Check Devices; if it was revoked in error, re-approve it with device approval.

Verify reports TAMPERED

surfil verifyrecomputes the hash from the document body. TAMPERED means the bytes don't match the signature - the receipt was altered after signing. A VALID result needs no account and works offline; if you get TAMPERED on a receipt you exported, re-export it from the source rather than trusting the altered copy.