Skip to main content

Troubleshooting

Troubleshooting

Start from the error that your application or terminal shows. Write down the response status, the error message, the request ID, and the time. With these, you can find the same request in Verdictan.

ProblemStart here
The CLI does not install or startRun verdictan doctor and read the failed checks.
A request returns an errorHandle gateway errors. A 401 is different from a policy block or a provider error.
The gateway is not connectedOpen Gateways, examine the last-seen time, and read the error in the gateway terminal. See Connected Gateway Relay.
A request is blocked and you do not know whyInvestigate a Blocked Request
Requests complete but do not show in the ConsoleRequests do not show
An agent or another resource is missingA resource is missing
An IDE cannot connectIDE Troubleshooting

Check the CLI and gateway​

These commands only read. They examine the installation and your signed-in CLI profile:

verdictan doctor --json
verdictan auth whoami --json
verdictan regions current

Correct the first failure before you continue. auth whoami uses your CLI sign-in or an administrator token. Do not use a gateway runtime token for it.

On the host that runs the gateway, check the process:

curl --fail-with-body http://127.0.0.1:41002/healthz
curl --fail-with-body http://127.0.0.1:41002/readyz

Use your --listen port if it is not 41002. /healthz checks that the process runs. /readyz reports the state of the control connection, distributed state, and audit log. Neither route calls a model.

If you changed a local configuration file, validate it with the same provider variables and secret access as the gateway service:

verdictan policy lint --file policy-config.yaml
verdictan gateway check --config policy-config.yaml
Read the active configuration and provider metrics of a local gateway

These endpoints take the gateway runtime token. Set VERDICTAN_API_TOKEN to it in this terminal only, and do not send it to an organization API endpoint.

curl --fail-with-body http://127.0.0.1:41002/verdictan/config \
  -H "Authorization: Bearer $VERDICTAN_API_TOKEN"

curl --fail-with-body http://127.0.0.1:41002/verdictan/providers/metrics \
  -H "Authorization: Bearer $VERDICTAN_API_TOKEN"

Compare config.config_version and config.config_sha256 with the deployed version. config.policy_chain lists the active rules.

Requests do not show​

  1. Make sure that the application calls your agent URL or gateway URL. A request sent directly to a provider does not go through Verdictan.

  2. Open Gateways and examine the last-seen time of the gateway.

  3. Make sure that the Console and the CLI use the same organization and region as the gateway.

  4. Search the delivered events for the request ID:

    verdictan events tail --since 10m --limit 20 --json

If the event exists but History is empty, examine the capture settings and your permission to view sessions. History holds captured content only. An empty History view does not prove that no request occurred.

More requests are blocked or reviewed​

Compare the start of the increase with the latest deployment in Configurations. Examine two or more of the affected request IDs: their errors, decisions, reason codes, and configuration versions. If requests wait for human review, also examine Inbox.

The same time alone does not prove the cause. A provider failure or an application change can occur in the same period. If the policy change is the cause, follow the rollback steps in Managing Policy Changes.

A user cannot do an action​

Examine the selected organization and the role of the user. Ask an organization administrator to compare the role with the action in the Permissions Reference.

A gateway policy does not give a person permission to manage organization settings, members, or billing.

A resource is missing​

Run verdictan regions current. Compare its API address and region with the region of the resource. Also examine the organization and your permissions.

To change the default region of the CLI profile:

verdictan configure set region eu-west --profile default
verdictan regions current --profile default

Use the region that owns the resource. A profile change does not move the resource or change a published agent URL.

Use a different region for one command​

Use the --region option of the command itself:

verdictan events tail --region eu-west --since 10m --json

The top-level verdictan --region option sets process context. API commands do not use it. See Select a region.

If model traffic goes to the wrong location, examine the provider routing and the agent hostname. A CLI profile does not change them.

Prepare evidence for help​

Collect the request IDs, the timestamps with their time zone, the region, the gateway or agent ID, and the active configuration version. Add the failed command with credentials removed, and a short description of the result.

To get an export, see Export Evidence for a Review. Do not include provider keys, application tokens, gateway tokens, or customer content that the reviewer does not need.

Escalate​

Contact the operator of your organization if production requests fail, a rollback needs authorization, or you think that someone misused the system. Give them the evidence above.

Next steps​