> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Troubleshoot common Foil integration issues: null sessions, sealed token failures, inconclusive verdicts, Gate webhook 401s, and CLI errors, plus FAQs.

## Common errors

### `getSession()` returns null or throws

**Cause:** The Foil SDK hasn't finished initializing.

**Fix:** Ensure `Foil.start()` has resolved before calling `getSession()`. If you need the fingerprint to be complete, await `waitForFingerprint()` first.

### Sealed token verification fails

**Cause:** The publishable key used in the browser and the secret key used on the server belong to different organizations.

**Fix:** Verify both keys are from the same organization. Check the dashboard for your active key pairs.

### All sessions return `inconclusive`

**Cause:** The behavioral phase hasn't collected enough interaction data.

**Fix:** Don't call `getSession()` immediately on page load. Wait until the user has interacted with the page (clicked, typed, scrolled).

### Gate webhook returns 401

**Cause:** The `X-Foil-Signature` header doesn't match.

**Fix:** Verify you're computing the HMAC over `${timestamp}.${rawBody}` using both the `X-Foil-Timestamp` and the raw request bytes (not `JSON.stringify(req.body)` which may reorder keys).

### `npx signup` says "Service not found"

**Cause:** The service isn't registered in the Gate registry, or the registry URL is wrong.

**Fix:** Run `npx signup list` to see available services. For development, pass `--registry-url http://localhost:3000/gate/registry`.

### Dashboard login redirects to /login

**Cause:** The login code was already consumed or expired, or `GATE_API_ORIGIN` points to the wrong server.

**Fix:** Login codes are one-time-use and expire in 5 minutes. Ensure your dashboard server's `GATE_API_ORIGIN` points to the same API that issued the code.

## FAQ

**Q: Does Foil add latency to my pages?**
A: The browser SDK loads asynchronously and doesn't block rendering. The `getSession()` call adds \~50-200ms depending on how much behavioral data has been collected.

**Q: What happens if the Foil CDN is down?**
A: Your application continues to work. The SDK fails gracefully — `getSession()` returns null, and you should have a fallback policy (e.g., allow the request but flag it for review).

**Q: Can I use Foil with a Content Security Policy?**
A: Yes. Add `cdn.usefoil.com` to your `script-src` directive and `api.usefoil.com` to your `connect-src` directive.

**Q: How long are sessions stored?**
A: Sessions are available via the API for 90 days. Fingerprints are stored for 1 year.

## Still stuck?

Contact us at [support@abxylabs.com](mailto:support@abxylabs.com) or open an issue on GitHub.