Troubleshooting
Use this page when the platform is available but the customer workflow does not have the necessary result.
No recent traffic is shown
- Make sure that you are viewing the correct environment.
- Verify that the gateway continues to forward requests.
- Open Gateways and make sure that the selected runtime is healthy.
- Query runtime Events with
verdictan events tail --since 10m --json. Verify that matching request IDs are being delivered. - If history capture is enabled, examine History in a different step 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, cause codes, and configuration versions.
- If capture is enabled, use History for the permitted session context. The capture mode and platform retention policy control this context.
- Open Inbox if the issue is review volume and not direct blocking.
Users cannot do a task
- Verify that the user has the correct role for the environment.
- Identify if the missing action belongs in Organization, Settings, Bills, or Payments and not in the runtime workflow.
- Route unresolved access issues to an organization administrator, not to policy reviewers.
Evidence exports are hard to reuse
- Include the request identifiers, time window, and environment name with each export.
- Record if the export supports an audit, customer incident, or compliance review.
- Keep the configuration version or rollout context next to the export when possible.
You cannot find a resource
- Run
verdictan regions current. Make sure that it shows the selected region and API endpoint. - Identify if the resource or provider target is in a different region.
- If
policy-config.yamlcontrols the workflow, examine the declarative config and published hostname. Make sure that they specify the selected locality. - A change to
~/.verdictan/config.yamlchanges only the CLI region defaults. - If you use a Verdictan-managed public hostname, make sure that its locality matches the workload locality.
- An empty or unavailable region result can show a locality mismatch. It does not prove that the resource is missing in all regions.
A workflow specifies a region
- Set a profile default with
verdictan configure set region <region> --profile <profile>. - For an API-backed command, use the region option for that command. For example,
verdictan events tail --region <region>. The top-levelverdictan --region <region> ...form is a compatibility shim for the local gateway process context. It is not the usual override for an API command. - If runtime traffic fails, correct the region in
policy-config.yamlor the published hostname. A change to only the CLI profile is not sufficient. - Examine
VERDICTAN_CONFIGif you use a non-default config file path. - Re-run
verdictan 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 use the default gateway port
41002. If you configured a custom--listenport, use that port in the URLs.
- CLI
- cURL
- Python
- Node.js
verdictan doctor --json
verdictan auth whoami --json
verdictan regions current
verdictan policy lint --file policy-config.yaml
verdictan events tail --since 10m --limit 20 --json
verdictan events tail --follow --event-type decision --verdict blocked
curl http://localhost:41002/verdictan/config
curl http://localhost:41002/verdictan/providers/metrics
curl https://api.verdictan.com/v1/whoami \
-H "Authorization: Bearer $VERDICTAN_API_TOKEN"
import os
import httpx
print(httpx.get("http://localhost:41002/verdictan/config").json())
api_key = os.environ["VERDICTAN_API_TOKEN"]
headers = {"Authorization": f"Bearer {api_key}"}
whoami = httpx.get("https://api.verdictan.com/v1/whoami", headers=headers).json()
print(f"Authenticated as: {whoami}")
const config = await fetch("http://localhost:41002/verdictan/config").then((r) => r.json());
console.log(config);
const apiKey = process.env.VERDICTAN_API_TOKEN;
if (!apiKey) throw new Error("VERDICTAN_API_TOKEN is required");
const whoami = await fetch("https://api.verdictan.com/v1/whoami", {
headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
console.log("Authenticated as:", whoami);
Escalate when
- A production traffic block changes customer workflows.
- A recent rollout changed behavior and the rollback owner is not engaged.
- You find evidence of misuse, policy evasion, or a control gap that must be reviewed immediately.