Troubleshooting
Use this page when the platform is reachable but the customer workflow does not look right.
No recent traffic appears
- Confirm you are viewing the correct environment.
- Check whether the gateway is still forwarding requests.
- Open Gateways and confirm the expected runtime is healthy.
- Query runtime Events with
kt events tail --since 10m --jsonand confirm whether matching request IDs are being delivered. - If history capture is enabled, check History separately for captured session context. An empty History view does not prove traffic stopped.
Unexpected spikes in blocked or reviewed traffic
- Compare the timing with the latest policy change.
- Review a small sample from the same Events query, including request IDs, verdicts, reason codes, and configuration versions.
- When capture is enabled, use History for the additional session context allowed by the configured capture mode and platform retention policy.
- Check Inbox if the issue is really review volume rather than outright blocking.
People cannot do the job they expect
- Verify the user has the right role for the environment they are in.
- Confirm whether the missing action belongs in Organization, Settings, Bills, or Payments rather than the runtime workflow.
- Route unresolved access issues to an organization administrator, not to policy reviewers.
Evidence exports are hard to use later
- Include the request identifiers, time window, and environment name with every export.
- Record whether the export supports an audit, customer incident, or compliance review.
- Keep the configuration version or rollout context next to the export whenever possible.
I can't find my resource
- Run
kt regions currentand confirm the resolved region and API endpoint are the ones you intended. - Check whether the resource or provider target only exists in a different region than your current request scope.
- If the workflow is driven by
policy-config.yaml, confirm the declarative config or published hostname still points at the locality you expect. Changing~/.keeptrusts/config.yamlonly changes CLI-requested region defaults. - If you are using a Keeptrusts-managed public hostname, confirm the hostname's locality matches the workload you expect.
- Treat an empty or unavailable region-scoped result as a locality mismatch to investigate first, not as proof that the resource is missing everywhere.
A workflow says a region is required
- Set a profile default with
kt configure set region <region> --profile <profile>. - For an API-backed command, use that command's own region option, for example
kt events tail --region <region>. The top-levelkt --region <region> ...form is only a compatibility shim for local gateway/runtime process context; it is not the ordinary API-command override. - If the failing step is runtime traffic rather than an API-backed CLI call, fix the region in
policy-config.yamlor the published hostname instead of only changing the CLI profile default. - Check
KEEPTRUSTS_CONFIGif you expect a non-default config file path. - Re-run
kt regions currentafter changing the profile default. For a command-local--region, verify the region and endpoint reported by that command's result or diagnostics.
Diagnostic commands
The examples below use the default gateway port
41002. If you configured a custom--listenport, substitute it in the URLs below.
- CLI
- cURL
- Python
- Node.js
kt doctor --json
kt auth whoami --json
kt regions current
kt policy lint --file policy-config.yaml
kt events tail --since 10m --limit 20 --json
kt events tail --follow --event-type decision --verdict blocked
curl http://localhost:41002/keeptrusts/config
curl http://localhost:41002/keeptrusts/providers/metrics
curl https://api.keeptrusts.com/v1/whoami \
-H "Authorization: Bearer $KEEPTRUSTS_API_TOKEN"
import os
import httpx
print(httpx.get("http://localhost:41002/keeptrusts/config").json())
api_key = os.environ["KEEPTRUSTS_API_TOKEN"]
headers = {"Authorization": f"Bearer {api_key}"}
whoami = httpx.get("https://api.keeptrusts.com/v1/whoami", headers=headers).json()
print(f"Authenticated as: {whoami}")
const config = await fetch("http://localhost:41002/keeptrusts/config").then((r) => r.json());
console.log(config);
const apiKey = process.env.KEEPTRUSTS_API_TOKEN;
if (!apiKey) throw new Error("KEEPTRUSTS_API_TOKEN is required");
const whoami = await fetch("https://api.keeptrusts.com/v1/whoami", {
headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
console.log("Authenticated as:", whoami);
Escalate when
- Production traffic is blocked in a way that affects customer workflows.
- A recent rollout changed behavior and the rollback owner is not yet engaged.
- You suspect misuse, policy evasion, or a control gap that requires immediate review.