urllib3 DNS lookup error exception (Fix)

The Fix

pip install urllib3==1.26.7

Based on closed urllib3/urllib3 issue #1003 · PR/commit linked

Production note: Watch p95/p99 latency and retry volume; timeouts can turn into retry storms and duplicate side-effects.

Jump to Verify Open PR/Commit

@@ -207,7 +207,7 @@ def _new_conn(self) -> socket.socket:
             )
         except socket.gaierror as e:
-            raise NameResolutionError(self.host, e)
+            raise NameResolutionError(self.host, self, e)
         except SocketTimeout:

repro.py

Traceback (most recent call last):
      File "check.py", line 11, in <module>
        status = requests.head('http://' + site)
      File "C:\Python27\lib\site-packages\requests\api.py", line 93, in head
        return request('head', url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\api.py", line 53, in request
        return session.request(method=method, url=url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 468, in request
        resp = self.send(prep, **send_kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 576, in send
        r = adapter.send(request, **kwargs)
      File "C:\Python27\lib\site-packages\requests\adapters.py", line 437, in send
        raise ConnectionError(e, request=request)
    requests.exceptions.ConnectionError: HTTPConnectionPool(host='jenkins.k8s.io', port=80):
        Max retries exceeded with url: / (Caused by
        NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at
        0x029E43B0>: Failed to establish a new connection: [Errno 11001] getaddrinfo failed',))

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

fix.md

Option A — Upgrade to fixed release\npip install urllib3==1.26.7\nWhen NOT to use: This fix should not be used if backward compatibility with previous error handling is required.\n\n

Why This Fix Works in Production

Trigger: status = requests.head('http://' + site)
Mechanism: The DNS resolution error handling was not specific enough, leading to confusion in exception handling
Why the fix works: Changes the parent class of NameResolutionError to NewConnectionError, solving various problems related to DNS resolution errors. (first fixed release: 1.26.7).

Production impact:

If left unfixed, tail latency can spike under load and surface as timeouts/retries (amplifying incident impact).

Why This Breaks in Prod

The DNS resolution error handling was not specific enough, leading to confusion in exception handling
Surfaces as: Traceback (most recent call last):

Proof / Evidence

GitHub issue: #1003
Fix PR: https://github.com/urllib3/urllib3/pull/2319
First fixed release: 1.26.7
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.27

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“Ok, so”

@Lukasa · 2016-10-20 · confirmation · source

“Too late. =) I've already done exception handling through string parsing - https://github.com/kennethreitz/requests/issues/3630#issuecomment-255100951”

@techtonik · 2016-10-20 · source

“So how about reusing Chrome's ERR_NAME_NOT_RESOLVED constant which seems to have cross-platform value -105? https://cs.chromium.org/chromium/src/net/base/net_error_list.h?sq=package:chromium&dr=C&rcl=1477077889&l=130 Or it could be NXDOMAIN error code 3 - http”

@techtonik · 2016-10-22 · source

“I don't know that we gain anything from using a constant: it's just not that Pythonic an approach”

@Lukasa · 2016-10-23 · source

Failure Signature (Search String)

status = requests.head('http://' + site)

Error Message

Stack trace

error.txt

Error Message
-------------
Traceback (most recent call last):
      File "check.py", line 11, in <module>
        status = requests.head('http://' + site)
      File "C:\Python27\lib\site-packages\requests\api.py", line 93, in head
        return request('head', url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\api.py", line 53, in request
        return session.request(method=method, url=url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 468, in request
        resp = self.send(prep, **send_kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 576, in send
        r = adapter.send(request, **kwargs)
      File "C:\Python27\lib\site-packages\requests\adapters.py", line 437, in send
        raise ConnectionError(e, request=request)
    requests.exceptions.ConnectionError: HTTPConnectionPool(host='jenkins.k8s.io', port=80):
        Max retries exceeded with url: / (Caused by
        NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at
        0x029E43B0>: Failed to establish a new connection: [Errno 11001] getaddrinfo failed',))

Stack trace

error.txt

Error Message
-------------
Traceback (most recent call last):
  File "check.py", line 11, in <module>
    status = requests.head('http://' + site)
  File "C:\Python27\lib\site-packages\requests\api.py", line 93, in head
    return request('head', url, **kwargs)
  File "C:\Python27\lib\site-packages\requests\api.py", line 53, in request
    return session.request(method=method, url=url, **kwargs)
  File "C:\Python27\lib\site-packages\requests\sessions.py", line 468, in request
    resp = self.send(prep, **send_kwargs)
  File "C:\Python27\lib\site-packages\requests\sessions.py", line 576, in send
    r = adapter.send(request, **kwargs)
  File "C:\Python27\lib\site-packages\requests\adapters.py", line 437, in send
    raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPConnectionPool(host='jenkins.k8s.io', port=80):
    Max retries exceeded with url: / (Caused by
    NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at
    0x029E43B0>: Failed to establish a new connection: [Errno 11001] getaddrinfo failed',))

Minimal Reproduction

repro.py

Traceback (most recent call last):
      File "check.py", line 11, in <module>
        status = requests.head('http://' + site)
      File "C:\Python27\lib\site-packages\requests\api.py", line 93, in head
        return request('head', url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\api.py", line 53, in request
        return session.request(method=method, url=url, **kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 468, in request
        resp = self.send(prep, **send_kwargs)
      File "C:\Python27\lib\site-packages\requests\sessions.py", line 576, in send
        r = adapter.send(request, **kwargs)
      File "C:\Python27\lib\site-packages\requests\adapters.py", line 437, in send
        raise ConnectionError(e, request=request)
    requests.exceptions.ConnectionError: HTTPConnectionPool(host='jenkins.k8s.io', port=80):
        Max retries exceeded with url: / (Caused by
        NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at
        0x029E43B0>: Failed to establish a new connection: [Errno 11001] getaddrinfo failed',))

What Broke

Users experienced unclear exceptions when DNS resolution failed, impacting error handling in production.

Why It Broke

The DNS resolution error handling was not specific enough, leading to confusion in exception handling

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install urllib3==1.26.7

When NOT to use: This fix should not be used if backward compatibility with previous error handling is required.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/urllib3/urllib3/pull/2319

First fixed release: 1.26.7

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix should not be used if backward compatibility with previous error handling is required.

Verify Fix

verify

Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Track RSS + object counts after deployments; alert on monotonic growth and GC pressure.
Add a long-running test that repeats the failing call path and asserts stable memory.

Version Compatibility Table

Version	Status
1.26.7	Fixed

Related Issues

No related fixes found.

Cluster: urllib3:timeout urllib3 hub urllib3 best practices All hubs All clusters

Related clusters: Configuration error Data consistency SSL handshake

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.