{"id":"52d88de5d1ba66e3","repo":"pypa/pip","slug":"proxy-connection-failed","errorCode":"proxy-connection-failed","errorMessage":"Failed to connect to proxy {proxy} while fetching {url}","messagePattern":"Failed to connect to proxy (.+?) while fetching (.+?)","errorType":"exception","errorClass":"ProxyConnectionError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/network/utils.py","lineNumber":201,"sourceCode":"    if not isinstance(reason, urllib3.exceptions.MaxRetryError):\n        raise ConnectionFailedError(url, raw_hostname, reason)\n\n    max_retry_error = reason\n    assert isinstance(max_retry_error.pool, urllib3.connectionpool.HTTPConnectionPool)\n    host = max_retry_error.pool.host\n    proxy = max_retry_error.pool.proxy\n    # Narrow the reason further to the specific error from the last retry.\n    reason = max_retry_error.reason\n\n    if isinstance(reason, urllib3.exceptions.SSLError):\n        raise SSLVerificationError(url, host, reason)\n    if isinstance(reason, urllib3.exceptions.TimeoutError) and not isinstance(\n        reason, urllib3.exceptions.NewConnectionError\n    ):\n        _raise_timeout_error(reason, url, host, timeout)\n    if isinstance(reason, urllib3.exceptions.ProxyError):\n        assert proxy is not None\n        raise ProxyConnectionError(url, redact_auth_from_url(str(proxy)), reason)\n\n    # Unknown error, give up and raise a generic error.\n    raise ConnectionFailedError(\n        url, host, reason if isinstance(reason, Exception) else max_retry_error\n    )\n","sourceCodeStart":183,"sourceCodeEnd":207,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/network/utils.py#L183-L207","documentation":"Raised as ProxyConnectionError when pip cannot establish a connection to a configured HTTP(S) proxy while downloading a package. It is produced inside raise_connection_error() after urllib3 exhausts its retries and reports the final failure reason as a urllib3 ProxyError. The proxy URL in the message is redacted of credentials via redact_auth_from_url.","triggerScenarios":"A proxy is configured (via --proxy, HTTP_PROXY/HTTPS_PROXY env vars, or pip config) and the TCP connection to that proxy host:port fails or the proxy refuses the CONNECT tunnel. The urllib3 MaxRetryError.reason is an instance of urllib3.exceptions.ProxyError at utils.py:199-201.","commonSituations":"Corporate networks behind a proxy where the proxy hostname is mistyped, the port is blocked by a firewall, the proxy is temporarily down, or credentials are wrong. Also common when HTTPS_PROXY points to an HTTP-only proxy that cannot tunnel HTTPS, or when a VPN drops mid-download.","solutions":["Verify the proxy URL is reachable: test with curl -x <proxy_url> <package_url> or nc -vz <proxy_host> <proxy_port>.","Check pip's effective proxy config: pip config list and echo $HTTP_PROXY $HTTPS_PROXY.","Remove or correct the proxy setting: pip install --proxy '' <pkg> or unset HTTP_PROXY HTTPS_PROXY if a stale proxy env var leaks into the shell.","If the proxy requires auth, ensure credentials are embedded correctly in the URL (https://user:pass@host:port) and that the proxy supports CONNECT tunneling for HTTPS.","Retry after confirming network/firewall allows outbound traffic to the proxy host and port."],"exampleFix":"# before\nexport HTTPS_PROXY=http://prox.my-corp.com:8080\npip install requests\n\n# after (corrected hostname)\nexport HTTPS_PROXY=http://proxy.my-corp.com:8080\npip install requests","handlingStrategy":"retry","validationCode":"import socket, urllib.parse\nproxy = os.environ.get(\"HTTPS_PROXY\") or os.environ.get(\"HTTP_PROXY\")\nif proxy:\n    parsed = urllib.parse.urlparse(proxy)\n    host, port = parsed.hostname, parsed.port or (443 if parsed.scheme == \"https\" else 80)\n    try:\n        socket.create_connection((host, port), timeout=5).close()\n    except OSError as e:\n        raise SystemExit(f\"proxy unreachable: {host}:{port} -> {e}\")","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import ProxyConnectionError\ntry:\n    install_pkg(req)\nexcept ProxyConnectionError as e:\n    logger.warning(\"proxy down; retrying without proxy: %s\", e)\n    run([sys.executable, \"-m\", \"pip\", \"install\", \"--proxy\", \"\", req])","preventionTips":["Validate proxy reachability in CI before running pip.","Pin proxy config in pip.conf rather than relying on shell env vars that can leak across tools.","Configure --retries and --timeout so transient proxy blips self-heal."],"tags":["network","proxy","connection","download"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}