IDE Integration Troubleshooting

When an editor can't reach Verdictan, first make the same request from a terminal. If the terminal works, the problem is in the editor's settings, and you compare them value by value. Model requests and MCP tools fail independently, so work out which one is failing first.

Before you start

• A shell on the machine that runs verdictan gateway run.
• The client API token the editor uses.
• A CLI session with events:read, from VERDICTAN_API_TOKEN or verdictan auth login.

Identify the failing path

Path	Endpoint	Token	How failure shows
Model traffic	http://127.0.0.1:41002/v1, or a published model hostname	Client API token, as a Bearer token	An HTTP status in the editor, or no event
MCP tools	https://<published-hostname>/mcp	Client API token, as a Bearer token	An MCP status or JSON-RPC error in the editor's MCP log

If MCP connects but no model events appear, you only set up MCP. It adds tools and does not change where the editor sends model requests. See the IDE Integration Overview for what each editor supports.

Verify the gateway from the shell

On the same machine as the editor:

1. Check that the process is up:

   curl --fail http://127.0.0.1:41002/healthz

2. List models with the editor's token:

   export VERDICTAN_CLIENT_TOKEN="<client-api-token>"
   
   curl --fail http://127.0.0.1:41002/v1/models \
     -H "Authorization: Bearer ${VERDICTAN_CLIENT_TOKEN}"

3. Send the short model request with the same token and model. Health and model listing can succeed while the upstream call fails.

If the model request works, compare its exact URL, token, and model with the editor's settings.

Model endpoint failures

Symptom	Cause	Fix
Connection refused on port 41002	The gateway isn't running, or listens elsewhere	Start it as in Gateway Setup for IDEs, and check /healthz.
401 Unauthorized	The token is not an active client token, or the editor didn't read the variable	Check the token in the Console, and start the editor from a shell that exports it. Never use the gateway runtime token.
403 Forbidden	A role, binding, model, provider, budget, or publication limit on the token excludes the request	Compare the token's limits with the model and gateway the editor uses.
404 Not Found	The editor builds a URL the gateway doesn't serve	Use the /v1 base in a base-URL field, and the full route in a full-URL field.
The editor rejects the model	The ID doesn't match a provider target	Use an id from the authenticated GET /v1/models response.
The token went to the vendor	The editor's model client still uses the vendor's base URL	Point the base URL at the gateway, then rotate the token.
Requests fail through HTTP_PROXY or HTTPS_PROXY	The gateway is not a forward proxy	Remove the proxy setting, and set a custom base URL in the model client.

MCP endpoint failures

Symptom	Cause	Fix
mcp_publication_required	The URL is not a published agent hostname	Use the publication hostname, not localhost:41002 or the control-plane API.
401 with missing_api_key or invalid_api_key	No Bearer token, or one that is not a vdt_ Verdictan token	Send an active client API token.
403 with mcp_disabled_for_agent	MCP is turned off in the agent's resolved configuration	Turn MCP on in the agent or gateway configuration, and reconnect.
The server isn't listed	The editor can't read the variable in its MCP config, or the JSON is invalid	Start the editor from a shell that exports the variable, and validate the JSON.
The server is listed but has no tools	Tool authorization, enabled tools, or transport support	Read the editor's MCP log, then check the token's permissions and the enabled tools.
Opening /mcp in a browser fails	/mcp requires MCP transport headers and messages	Test with an MCP client instead.

Missing events

A matching event proves a request went through Verdictan; a missing one doesn't prove it bypassed the gateway. Send one request from the editor, run verdictan events tail --since 10m after it, and check in this order:

Symptom	Cause	Fix
No events found. for every request	The gateway doesn't deliver events, or its runtime token is wrong or inactive	Check VERDICTAN_API_TOKEN in the gateway's environment, and that it runs connected with --agent.
Other gateways' events appear, but not this one's	The CLI profile queries another organization, API URL, or region	Compare verdictan auth whoami and verdictan regions current with the gateway's environment.
Events arrive late or outside the window	--since or a filter excludes them	Widen --since, and drop --event-type, --verdict, and --gateway-id.
The editor gets a reply but no event appears	The editor uses another base URL or model	Check the active base URL and model in the editor, and compare with a curl request.
Chat events appear, inline completions don't	The inline feature uses a vendor endpoint or another adapter	Check which model or adapter the inline feature uses.

Policy and latency problems

If the editor still uses earlier rules, check configuration sync status in Gateways. With CLI 0.1.14 or later, deploy the corrected file through the agent. Wait for In sync on gateway 0.1.14 or later. Then repeat the editor request and examine its decision.

Symptom	Cause	Fix
A request is blocked or redacted unexpectedly	A control in the chain matched	Read the verdict and policy in the event, change only that control, and run verdictan policy lint and verdictan policy test before restarting.
Every request is blocked	A policy, token limit, budget, or provider error	Read the response code and policy reason before changing settings.
Responses are slow	An output control holds the response, or the provider is slow	Compare /healthz and /v1/models timing with one model request. Keep output controls off the inline chain; see Configure Policies for IDE Traffic.
The stream starts late	pii-detector holds the whole response to redact it	Expected with output redaction. Use non-streaming if the client can't handle it.

Don't turn off every control to fix one false positive.

Region problems

Symptom	Cause	Fix
Region-scoped results are empty	The CLI queries a region the gateway doesn't use	Run verdictan regions current, then choose the gateway's region with --region or your profile.
The published hostname resolves to another region	The publication and the gateway configuration disagree	Compare the hostname, gateway configuration, and CLI profile. verdictan regions current doesn't change a publication.

Next steps

• Gateway Setup for IDEs: start the connected gateway with the right agent, and check the model endpoint.
• API Tokens for IDEs: check a token's limits, or rotate it.
• Gateway MCP Surface: the MCP endpoint's connection details.