{"record":{"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/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/network/utils.py#L183-L207","documentation":"Raised as ProxyConnectionError when, after narrowing a MaxRetryError, the terminal reason is a urllib3.exceptions.ProxyError: pip could not connect to the configured HTTP(S) proxy. The message names the proxy and the URL being fetched.","triggerScenarios":"HTTPS_PROXY/HTTP_PROXY env vars or --proxy point at a proxy that is down, refusing connections, requiring unavailable auth, or unreachable; pip's connection pool reports a ProxyError on the final retry.","commonSituations":"Corporate proxy offline after VPN disconnect; stale proxy env vars on a developer machine; proxy port wrong; proxy requires auth that was not configured; proxy TLS intercept failing.","solutions":["Verify the proxy host:port is up and reachable (curl --proxy ...).","Correct or remove HTTPS_PROXY/HTTP_PROXY env vars and the --proxy option.","Provide proxy credentials if the proxy requires auth.","Ensure no_proxy excludes the index host only if intended."],"exampleFix":"# before\nHTTPS_PROXY=http://proxy.corp:3128 pip install pkg   # proxy down\n\n# after\nunset HTTPS_PROXY HTTP_PROXY && pip install pkg","handlingStrategy":"validation","validationCode":"import os, socket\n\ndef proxy_reachable() -> bool:\n    proxy = os.environ.get(\"HTTPS_PROXY\") or os.environ.get(\"HTTP_PROXY\")\n    if not proxy:\n        return True\n    from urllib.parse import urlsplit\n    p = urlsplit(proxy)\n    try:\n        with socket.create_connection((p.hostname, p.port or 8080), timeout=5):\n            return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import ProxyConnectionError\n\ntry:\n    run_pip_install([\"pkg\"])\nexcept ProxyConnectionError:\n    # unset stale proxy and retry, or fix proxy config\n    for k in (\"HTTPS_PROXY\", \"HTTP_PROXY\"):\n        os.environ.pop(k, None)\n    run_pip_install([\"pkg\"])","preventionTips":["Keep HTTPS_PROXY/HTTP_PROXY accurate; unset when off-VPN.","Provide proxy credentials in the proxy URL when required.","Verify the proxy host:port is up before installing."],"tags":["network","proxy","connection"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}