{"record":{"id":"b2f6fe3ba5390da5","repo":"pypa/pip","slug":"connection-failed","errorCode":"connection-failed","errorMessage":"Failed to connect to {host} while fetching {url}","messagePattern":"Failed to connect to (.+?) while fetching (.+?)","errorType":"exception","errorClass":"ConnectionFailedError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/network/utils.py","lineNumber":184,"sourceCode":"    url = redact_auth_from_url(url)\n    raw_hostname = urlsplit(url).hostname or urlsplit(url).netloc\n    reason = error.args[0] if error.args else error\n\n    # NewConnectionError is a subclass of TimeoutError for some reason...\n    if isinstance(reason, urllib3.exceptions.TimeoutError) and not isinstance(\n        reason, urllib3.exceptions.NewConnectionError\n    ):\n        # A bare timeout error can occur during non-streamed responses. Don't\n        # ask me how.\n        _raise_timeout_error(reason, url, raw_hostname, timeout)\n    if isinstance(reason, urllib3.exceptions.SSLError):\n        # A bare SSL error can occur during non-streamed responses, after the\n        # initial connection and TLS handshake have completed.\n        raise SSLVerificationError(url, raw_hostname, reason)\n\n    # At this point, all errors should be wrapped in MaxRetryError.\n    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","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/network/utils.py#L166-L202","documentation":"Raised as ConnectionFailedError (the not-MaxRetryError fallback) when the connection error's reason is neither a urllib3 TimeoutError, SSLError, nor a MaxRetryError. It is the generic catch-all for unrecognized connection-layer failures during non-streamed responses, with message 'Failed to connect to {host} while fetching {url}'.","triggerScenarios":"A requests.ConnectionError surfaces whose underlying reason does not fit the known urllib3 exception types (not timeout, not SSL, not MaxRetryError), e.g. an unexpected OS-level socket error or a novel urllib3 exception.","commonSituations":"DNS mis-resolution, connection reset, intermittent OS-level socket errors, library/urllib3 version mismatches surfacing new exception types.","solutions":["Read the wrapped error details pip prints for the underlying cause.","Verify host reachability and DNS resolution.","Retry the install; transient resets often clear.","Check for an outdated or mismatched urllib3/requests and update pip."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import socket\n\ndef host_resolves_and_connects(host: str, port: int = 443) -> bool:\n    try:\n        socket.getaddrinfo(host, port)\n        with socket.create_connection((host, port), timeout=5):\n            return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":"from pip._internal.exceptions import ConnectionFailedError\n\ntry:\n    run_pip_install([\"pkg\"])\nexcept ConnectionFailedError:\n    # inspect details, verify DNS/network, then retry\n    run_pip_install([\"pkg\"])","preventionTips":["Verify DNS resolution and outbound connectivity before installs.","Keep urllib3/requests versions consistent (use pip's vendored copies).","Retry after confirming the underlying cause from pip's printed context."],"tags":["network","connection","fallback"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}