Skip to content

data-claude-code-agent-proxy-troubleshooting-guide.md

Latest commit

 

History

History
99 lines (79 loc) · 4.91 KB

data-claude-code-agent-proxy-troubleshooting-guide.md

File metadata and controls

99 lines (79 loc) · 4.91 KB
Raw

Claude Code agent proxy

Outbound HTTPS from this session goes through a local proxy at ${AGENT_PROXY_URL} (set via HTTPS_PROXY) which tunnels to a policy-enforcing egress proxy. TLS is re-terminated there, so every tool must trust the CA bundle at ${AGENT_PROXY_CA_BUNDLE_PATH}. The standard CA environment variables, the system trust store (where possible), a JVM truststore, the Bazel system bazelrc, the browser NSS store, and gsutil's boto config are already set up.

Quick diagnosis

  1. Run: curl -sS ${AGENT_PROXY_URL}/__agentproxy/status It reports proxy state, which trust and git accommodations are active (javaTrustStorePath, toolTrustFailureCodes, gitSshRewrite, gitConfigConflicts), and the most recent proxy-side failures.
  2. Find the failure class below and apply the matching fix; gitConfigConflicts codes map to the git section, toolTrustFailureCodes to the JVM section.
  3. Never disable TLS verification, never unset HTTPS_PROXY, and do not retry organization policy denials (403/407) — report them instead.

Failure classes and fixes

"certificate verify failed" / "self-signed certificate in chain" / PKIX errors

The failing tool is not reading the pre-set CA configuration. In order:

  • If the tool has a CA flag or env var, point it at ${AGENT_PROXY_CA_BUNDLE_PATH} (examples: --cacert, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, AWS_CA_BUNDLE, DENO_CERT, CARGO_HTTP_CAINFO, PIP_CERT, GIT_SSL_CAINFO, BUNDLE_SSL_CA_CERT, HEX_CACERTS_PATH, NIX_SSL_CERT_FILE).
  • Tool config files override environment variables. If one of these sets its own CA or disables verification, point it at the bundle instead: pip.conf "cert", npm "cafile" (npm config get cafile), ~/.curlrc "cacert", .wgetrc "ca_certificate", conda "ssl_verify", git "http.sslCAInfo", gradle.properties / MAVEN_OPTS "-Djavax.net.ssl.trustStore".
  • JVM tools (Maven, Gradle, plain Java): when a JDK is present, a truststore is built at ${AGENT_PROXY_STATE_DIR}/java-truststore.p12 (password "changeit") and injected via JAVA_TOOL_OPTIONS — confirm javaTrustStorePath is set in the status output before pointing a build at it (toolTrustFailureCodes explains why it is missing). If the image or the build sets its own trustStore, that one wins — import the proxy CA into it with keytool -importcert -noprompt -alias ccr-agent-proxy -file ${AGENT_PROXY_STATE_DIR}/agent-proxy-ca.crt -keystore or point the build at the ready-made one. Bazel reads the managed block in /etc/bazel.bazelrc rather than JAVA_TOOL_OPTIONS.

"405 Method Not Allowed" from the proxy

The tool sent a plain-HTTP (non-CONNECT) request: usually axios older than 1.16.1 (upgrade it) or a tool configured with HTTP_PROXY (unset HTTP_PROXY for that tool — only HTTPS_PROXY is supported).

403 / 407 from the proxy

The destination host is not allowed by your organization's egress policy for this session. Do not retry or route around it — report the blocked host. Note: curl hides response bodies on failed CONNECTs; the status endpoint records the reason.

Tool ignores the proxy entirely (timeouts with no proxy error)

Some clients do not read HTTPS_PROXY: Node's built-in fetch (run that command with NODE_USE_ENV_PROXY=1 on Node >= 22.21), aiohttp (pass trust_env=True), Ruby bundler (reads only HTTP_PROXY, which this proxy does not serve), hand-rolled Go dialers. Prefer the tool's own proxy option where one exists.

git

SSH-form GitHub remotes (git@github.com:...) are rewritten to HTTPS automatically unless this session has its own SSH setup or supplies its own GIT_CONFIG_* (see gitSshRewrite in the status output). A gitconfig that sets http.proxy / http..proxy (even empty), its own http.sslCAInfo, or an https-to-ssh insteadOf makes git bypass the proxy or fail verification — the status output's gitConfigConflicts codes name which of these were detected; adjust those keys for this session if git times out.

docker build / docker run

Processes inside containers cannot reach 127.0.0.1:${AGENT_PROXY_PORT} and do not trust the CA. Workarounds: run builds with --network host, copy ${AGENT_PROXY_CA_BUNDLE_PATH} into the build context and install it in an early layer, and pass proxy/CA settings explicitly to the build.

Not supported through the proxy (report, do not work around)

gRPC / HTTP/2-only APIs, WebSocket upgrades, client-mTLS, certificate-pinned clients (e.g. Snowflake, ngrok), non-443 HTTPS ports, raw-TCP databases.

If a tool still cannot work through the proxy, report it to your administrator or Anthropic support so the policy or tooling can be fixed.