IDE Integration Troubleshooting

This guide covers the most common issues you encounter when connecting IDE AI assistants to the Keeptrusts gateway, with step-by-step solutions for each.

Use this page when

• You are working through IDE Integration Troubleshooting as an implementation or operating workflow in Keeptrusts.
• You need the practical steps, expected outcomes, and related validation guidance in one place.
• If you need exact field-by-field reference instead of a workflow page, use the linked reference pages in Next steps.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Connection Refused

Symptom: The IDE extension shows "Connection refused" or "ECONNREFUSED" errors.

Causes and fixes:

1. Gateway not running — start it:

   kt gateway run --policy-config policy-config.yaml

2. Wrong port — verify the gateway is listening on the expected port:

   curl http://localhost:41002/v1/models

3. Bound to wrong interface — if the gateway is on a remote machine, ensure it listens on 0.0.0.0:

   kt gateway run --listen 0.0.0.0:41002 --policy-config policy-config.yaml

4. Firewall blocking — check that port 41002 is open:

   # macOS
   sudo lsof -i :41002
   
   # Linux
   ss -tlnp | grep 41002

SSL/TLS Errors

Symptom: "SSL certificate problem", "unable to verify the first certificate", or "DEPTH_ZERO_SELF_SIGNED_CERT".

Causes and fixes:

1. Self-signed certificate — if using TLS on the gateway, add the CA to your system trust store:

   # macOS
   sudo security add-trusted-cert -d -r trustRoot \
     -k /Library/Keychains/System.keychain gateway-ca.crt
   
   # Linux (Debian/Ubuntu)
   sudo cp gateway-ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates

2. IDE ignoring system certs — some extensions use their own certificate bundle. Check extension settings for a "CA Certificate" or "Reject Unauthorized" option.

3. Use HTTP for local — if the gateway runs on localhost, use http://localhost:41002/v1 instead of HTTPS. TLS is only needed for remote gateways.

Authentication Failures

Symptom: 401 Unauthorized or "Invalid API key" errors.

Causes and fixes:

1. Wrong key type — ensure you are using an access key (not a gateway key) in the IDE extension settings.

2. Expired key — check key validity in the console under Settings → Access Keys.

3. Missing Bearer prefix — some extensions auto-add the Bearer prefix, others don't. If the extension has a raw header field, use:

   Authorization: Bearer your-access-key

4. Environment variable not set — if the extension reads from an environment variable, verify it:

   echo $KEEPTRUSTS_ACCESS_KEY

Slow Completions

Symptom: IDE completions take several seconds or feel sluggish compared to direct API access.

Causes and fixes:

1. Complex policy chain — each policy adds latency. Review your policy-config.yaml and keep the chain minimal for completions. See Recommended Policies for IDE Traffic.

2. Enable engineering cache — cached responses skip the LLM entirely:

   policies:
     - name: ide-cache
       type: cache
       config:
         enabled: true
         ttl_seconds: 3600

3. Use a faster model — for inline completions, use gpt-4o-mini or similar fast models.

4. Check upstream latency — verify the provider is responsive:

   kt events tail
   # Look at the latency column

Extension Not Using the Custom Endpoint

Symptom: Traffic goes directly to the provider and does not appear in kt events tail.

Causes and fixes:

1. Settings not saved — restart the IDE after changing extension settings.

2. Wrong setting field — double-check the extension's documentation for the correct setting name (e.g., apiBase vs. baseUrl vs. endpoint).

3. Extension uses its own auth flow — some extensions (like GitHub Copilot) authenticate directly with their service and ignore custom endpoints. Use proxy-based interception instead.

4. Multiple extension instances — if you have the same extension in both VS Code and JetBrains, check that you are editing the correct config file.

Policy Blocks (409 Responses)

Symptom: The IDE shows an error or empty completion, and kt events tail shows a BLOCK event.

Causes and fixes:

1. Check the blocked event — the event log shows which policy triggered the block:

   kt events tail
   # 2024-01-15T10:32:15Z  BLOCK  policy=content-filter  reason="blocked pattern detected"

2. Adjust the policy — if the block is a false positive (e.g., a regex pattern matching valid code), refine the policy regex.

3. Understand input vs. output blocks — input-phase blocks fire before the LLM call (fast), output-phase blocks fire after (costs tokens but catches unsafe completions).

Timeout Errors

Symptom: "Request timed out" or "ETIMEDOUT" errors from the IDE extension.

Causes and fixes:

1. Increase extension timeout — many extensions default to 10-30 seconds. For complex prompts or slow models, increase to 60-120 seconds.

2. Check gateway health:

   curl -w "time_total: %{time_total}s\n" http://localhost:41002/v1/models

3. Upstream provider timeout — the provider itself may be slow. Check the gateway events for upstream latency.

Proxy Configuration Conflicts

Symptom: Setting HTTP_PROXY for the gateway interferes with other network traffic in the IDE.

Causes and fixes:

1. Use NO_PROXY — exclude non-gateway traffic:

   export NO_PROXY="github.com,*.npmjs.org,localhost"

2. Extension-specific proxy — prefer configuring the endpoint URL directly in the extension settings rather than using system-wide proxy variables.

3. Scoped environment — launch the IDE with proxy variables set only for that process:

   HTTP_PROXY=http://localhost:41002 code .

Platform-Specific Issues

macOS

• Keychain prompts — some extensions store API keys in the macOS Keychain. Grant access when prompted.
• App Sandbox — sandboxed apps may not access localhost. Use 127.0.0.1 instead.

Linux

• Snap/Flatpak IDEs — containerized IDE installations may not access localhost. Configure the gateway to listen on the container's network interface.

Windows

• Corporate proxy — if your organization uses a mandatory proxy, configure the gateway to chain through it with HTTPS_PROXY.
• WSL — if running the gateway in WSL, use the WSL IP address (not localhost) from Windows-side IDEs.

Diagnostic Checklist

Run through this checklist when something isn't working:

• Gateway running: curl http://localhost:41002/v1/models
• Access key valid: check in console Settings → Access Keys
• Extension configured: correct base URL and API key
• IDE restarted after config changes
• Events visible: kt events tail shows traffic
• Policy chain reviewed: no overly broad blocks

For AI systems

• Canonical terms: Keeptrusts, IDE Integration Troubleshooting, ide-integration.
• Exact feature, config, command, or page names: IDE Integration Troubleshooting.
• Use the linked audience and reference pages in Next steps when you need deeper source material.

For engineers

• Use the commands, configuration examples, API payloads, or UI steps in this page as the working baseline for IDE Integration Troubleshooting.
• Validate the result with the expected outcomes, troubleshooting notes, or linked workflow pages in this page and Next steps.

For leaders

• This page matters when planning rollout, governance, support ownership, or operating decisions for IDE Integration Troubleshooting.
• Use the linked audience, architecture, and workflow pages in Next steps to connect this detail to broader implementation choices.

Next steps

• Gateway Setup for IDEs — verify your gateway configuration
• Access Keys and Authentication — manage IDE authentication
• Monitoring IDE AI Usage — review traffic and events