docs agent failed: intersphinx inventory fetch blocked behind corporate proxy
Fixes a docs agent whose intersphinx inventory fetch fails behind a corporate proxy. The skill shows how to configure proxy variables for the agent's environment, verify inventory reachability through the proxy, and cache inventories for offline builds. It covers authenticated proxies.
TL;DR
Set the proxy variables in the agent's build environment and verify the inventory URL is reachable through the proxy with curl. For unreliable networks, cache objects.inv locally and point intersphinx at the cache. Handle proxy auth without embedding credentials in the docs config.
The exact error
intersphinx inventory fetch blocked by proxySteps
Reproduce the fetch From the agent's environment, curl the inventory URL and observe the proxy block or timeout. Success check: You have the exact network failure.
Configure the proxy Set the standard proxy variables in the agent's environment so its HTTP client routes through the corporate proxy. Success check: The inventory URL is reachable through the proxy.
Handle proxy auth If the proxy needs authentication, provide it via the environment or a credentials helper, never hardcoded in docs config. Success check: Authenticated proxy access works without secrets in the repo.
Cache for reliability Download objects.inv on a schedule and point intersphinx at the local copy for routine builds. Success check: Docs build even when the upstream inventory is unreachable.
When to use
- Use when intersphinx fails only inside the corporate network.
- Use when an agent's docs build runs in a restricted network.
When not to use
- Not for inventory 404s (the URL is wrong, not blocked).
- Not for proxy issues in the deployed site (runtime, not build).
Why it happens
Build environments inside corporate networks route through proxies that block or authenticate external fetches. An agent's local build works because the developer machine has the proxy configured; the agent's sandbox does not.
Edge cases
Caching the inventory decouples the docs build from upstream availability entirely, which also speeds up builds. The proxy config belongs in the environment, not in conf.py, so it never leaks into the published docs.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_cTHVxYl9aigFRHjS1RwK7A