Troubleshooting
Symptom-first index of common Checkpoint issues: what you see, the likely cause, and the page that fixes it
Find the symptom you are seeing, check the likely cause, and follow the fix link. The full diagnostic steps live in each page's Troubleshooting section; this page is the index that gets you there.
CLI
| Symptom | Likely cause | Fix |
|---|---|---|
kya-os: command not found right after installing | ~/.kya-os/bin isn't on this shell's PATH yet | Open a new terminal, or run export PATH="$HOME/.kya-os/bin:$PATH". See Installation |
Installer: musl libc (e.g. Alpine) is not supported yet | No musl build of the CLI | Use a glibc-based image, or npm install -g @kya-os/cli with a glibc Node |
Installer: Windows is not supported by this installer yet | No native Windows build | Run the installer inside WSL. See Installation |
Installer: integrity check failed for downloaded package (sha512 mismatch) | The download doesn't match the registry's hash (a caching proxy, a bad mirror, or tampering) | Nothing was installed. Retry; if it persists, check --registry and any proxy in between |
kya-os setup waits for a browser that never opens | An SSH session or a headless machine | kya-os setup --device, then approve the code from any other device |
Native credential store is locked or inaccessible | macOS: the Keychain is locked or access was denied. Linux: no Secret Service keyring is running (servers, containers) | macOS: unlock the Keychain and allow access. Linux servers: sign in and link on your workstation, then on the server run kya-os detect install --project <id>, which needs no sign-in for the pixel and beacon |
This sign-in covers N projects. Choose one with --project | Several projects, and no terminal to ask in | Pass --project <id or name>, or set KYA_OS_PROJECT. A name no project has yet is offered for creation at sign-in |
… is not one of the projects this sign-in was granted | That project wasn't selected on the consent page when you signed in | kya-os login --project <id or name>, then grant it on the consent page, or create it there |
This sign-in was granted no projects | The organization has no project yet, or none was selected | Run kya-os setup again, and create or choose a project on the consent page |
Ignoring .kya-os/project.json: it links a project on … | The repository was linked against another Checkpoint (staging, a local server) | Set CHECKPOINT_API_URL to that origin, or relink with kya-os projects use <id> |
not applied without a terminal; re-run with --yes | CI, or an agent with no terminal | Review the printed plan, then rerun with --yes |
Server-side detection needs this project's runtime key | No CHECKPOINT_API_KEY in the app's .env.local or .env, and no sign-in to mint one (or the stack keeps its key elsewhere) | kya-os login, then rerun kya-os detect install --surface sdk to mint one; or kya-os checkpoint key set |
Your plan's API key limit is reached, so no key was minted | The plan's key cap counts every unrevoked key | Revoke an unused key in the dashboard, or store an existing one with kya-os checkpoint key set |
Checkpoint ended the management session | The session was revoked, went 30 days unused, or reached 90 days | kya-os login |
Install
| Symptom | Likely cause | Fix |
|---|---|---|
| Fresh install, no detections anywhere | Project ID wrong, or env vars not loaded by the runtime | Quickstart: not detecting agents |
| Not sure which credential goes in which env var | Project ID and API key each map to a specific variable per integration | Credentials |
| Next.js middleware never runs | proxy.ts/middleware.ts not at the project root (or in src/ for a src/ app), or the matcher skips your route | Next.js: middleware not running |
| Express middleware does nothing | tenantHost not set, or the middleware is mounted after your routes | Express: middleware not working |
.NET responses carry KYA-Detection: unavailable | The app pool runs 32-bit; the detection engine requires a 64-bit host process | .NET: detection unavailable on a 32-bit host |
.NET Framework: first request returns 500 with FileLoadException (0x80131040) | Binding redirects missing in a PackageReference project | .NET: FileLoadException |
.NET Framework: FileNotFoundException for wasmtime.dll | KyaOs.Checkpoint older than 0.2.2, or the project references only Checkpoint.Core | .NET: wasmtime.dll not found |
Detect
| Symptom | Likely cause | Fix |
|---|---|---|
| Pixel script not loading | Ad blocker or CSP blocking the script, or the Project ID is wrong | Pixel: not loading |
| Pixel loads but the dashboard stays empty | Project ID mismatch, unpublished GTM container, or the visitor sends Do Not Track | Pixel: no detections in dashboard |
| CSP violation for the pixel script | script-src does not allow https://kya.vouched.id | Pixel: Content Security Policy |
| Beacon throws "Project ID is required" | projectId missing or empty in the config | Beacon: Project ID required |
| Beacon sends nothing, and no errors appear | Do Not Track is honored by default, or a CSP, proxy, or tracker blocker blocks the request | Beacon: no detections in the dashboard |
| Beacon worker failures are invisible | Expected behavior: the Beacon falls back to the main thread; enable debug logging to see it | Beacon: worker failures |
| Custom events not appearing | Events are batched until the flush interval, and queued while offline | Beacon cookbook: events not appearing |
| Middleware verdicts computed but never reported | apiKey not set, so results stay local | Middleware cookbook: no detections in the dashboard |
onAgentDetected never fires (Next.js) | It only runs when a request is classified as an agent | Middleware cookbook: callback never fires |
req.checkpoint is undefined (Express) | Session tracking wiring (withSessionTracking plus cookie-parser) is missing | Middleware cookbook: req.checkpoint undefined |
| Too many false positives | Policy too aggressive for your traffic; observe before enforcing | Quickstart: too many false positives |
Enforce
| Symptom | Likely cause | Fix |
|---|---|---|
| Gateway status stuck on "Pending" | DNS record not detected: typo, conflicting records, or propagation still in progress | Gateway: DNS record not detected |
| Gateway status shows "Error" | Conflicting DNS records, unreachable origin, or CAA blocking certificate issuance | Monitoring: gateway shows Error |
| SSL certificate not provisioning | CAA records block issuance, or the Cloudflare proxy is on (the record must be DNS-only) | Gateway: SSL certificate not provisioning |
| Site returns 502 after adding the Gateway CNAME | The Gateway cannot reach your origin sidecar | Sidecar cookbook: 502 after CNAME |
| Apex DNS records keep reappearing | A hosting provider with DNS access recreates them | Sidecar cookbook: apex records rewritten |
| Agents not being blocked (Gateway) | Policy saved as a draft and never deployed, or the deployed-policy cache has not refreshed | Gateway cookbook: requests not being blocked |
| Blocking not working (middleware) | enforcementMode set to 'observe', or the route is outside the matcher | Enforce middleware cookbook: blocking not working |
| Everything gets blocked, humans included | A forbid rule is too broad | Enforce middleware cookbook: all requests blocked |
| Policy edits not taking effect (middleware) | Policies are cached for policyCacheTtlSeconds (default 300s), or the edit is still a draft | Express: policy changes not taking effect |
| Policy edits not live after Compose changes | Draft saved but not redeployed, or the gateway's policy cache has not expired | Policies cookbook: troubleshooting |
| Wrong verdict on a request | A different rule matched; forbid overrides permit | Policies cookbook: troubleshooting |
| High detection latency at the Gateway | Uncached signature key fetch, or a slow origin | Monitoring: high latency |
| Health endpoint reports the engine degraded | The WASM detection module failed to initialize | Monitoring: WASM not initialized |
| Gateway traffic missing from the dashboard | Project ID mismatch, or requests bypass the Gateway DNS | Monitoring: detection not appearing |
Govern
| Symptom | Likely cause | Fix |
|---|---|---|
redirect_uri_mismatch on the GitHub consent screen | The registered callback URL differs from what the gateway sends, character for character | GitHub connection: redirect_uri_mismatch |
| "Bad credentials" on tool calls after a successful connect | The GitHub token was revoked externally; the reconnect is manual | GitHub connection: bad credentials |
state mismatch in gateway logs on OAuth callback | Authorize and callback more than 10 minutes apart, or the flow finished in a different browser | GitHub connection: state mismatch |
| Checkpoint middleware returns 401 for every request | Wrong API key or project ID, or the client omits the _meta.proof.jws envelope | Migration cookbook: 401 for all requests |
| Scopes always empty | The delegation grants no scopes, tools are unregistered, or consent was skipped | Migration cookbook: scopes always empty |
| Proof verification fails | Private key does not match the DID, or the proof's validity window expired | Migration cookbook: proof verification fails |
| Tool marked protected in the dashboard, but the server still allows calls | The tool is not discovered or assigned to a protection yet, or the middleware's config cache (default 5 minutes) has not refreshed | Tool Protection: configuring tools |
| Identity not loading on a self-hosted server | .mcpi/identity.json missing, or MCP_IDENTITY_PRIVATE_KEY wrong | Self-host cookbook: identity not loading |
| Delegation verification fails on a self-hosted server | Wrong API key and project ID pair, or the proof is not a compact JWS | Self-host cookbook: delegation verification fails |
| Dashboard deploy pipeline fails | GitHub App not installed, repo name taken, or App permissions insufficient | Deploy cookbook: pipeline fails |
| Cloudflare deploy step fails | Token missing scopes, wrong account ID, or a worker name conflict | Deploy cookbook: Cloudflare deployment fails |
DID document empty at /.well-known/did.json | Identity secret not set on the deployed worker | Deploy cookbook: identity not resolving |
Dashboard and API
| Symptom | Likely cause | Fix |
|---|---|---|
429 with code RATE_LIMIT_EXCEEDED | Your plan's request rate is exceeded; the X-RateLimit-* response headers say when the window resets | API Reference: rate limits |
CORS error calling /api/v1/detect from a browser | The detect API is server-side only: it needs an API key, and keys must never ship to the browser. Use the Pixel or Beacon on the client | API Reference: which endpoints need a key |
401 with code AUTH_INVALID_API_KEY, AUTH_MISSING_CREDENTIALS, or AUTH_UNAUTHORIZED | Key sent in the wrong header (it belongs in X-API-Key), no key sent at all, or the key belongs to a different project | API Reference: authentication |
window.Checkpoint is undefined | The pixel script had not loaded when identify() ran | Identify Users cookbook: window.Checkpoint undefined |
| User badge not appearing in the Activity feed | identify() not reaching the API, or the data has not landed yet | Identify Users cookbook: badge not appearing |
| Identified user not showing in the dashboard | Pixel not loaded, project mismatch, or a CSP or network error | Identify Users cookbook: user not showing |
| Session resets on every page reload | Cookies blocked, or a Shopify buyer has not allowed analytics | Identify Users cookbook: session not persisting |
| "window is not defined" in Next.js | Browser-only code running during server-side rendering | Identify Users cookbook: window is not defined |
Still Stuck?
- Email support with the error message, the integration you use, and the steps to reproduce
- Ask in our Discord community