http.client.HTTPSConnection._tunnel raises AttributeError: 'NoneType' object has no attribute 'encode' when header value is None

Bug report

Bug Description

Calling http.client.HTTPSConnection._tunnel() raises AttributeError: 'NoneType' object has no attribute 'encode' when _tunnel_headers contains a header key with a None value.

This regression affects third-party libraries (such as Apache Thrift and CodeChecker) that pass header dictionaries containing None values into set_tunnel(..., headers=...) or HTTP connection objects.

In Python 3.10.21, _tunnel() introduced strict encoding of tunnel headers (value.encode("latin-1")) without checking if the header value is None.

Target Python Version

Python 3.10.21 (Regression introduced between 3.10.20 and 3.10.21)

Operating System

Linux / Ubuntu

Code to Reproduce

import http.client

conn = http.client.HTTPSConnection("127.0.0.1", 8080)

# Set tunnel with a header value of None
conn.set_tunnel("example.com", 443, headers={"X-Test-Header": None})

# Call _tunnel() to trigger the issue
conn._tunnel()

Expected Behavior

_tunnel() should gracefully handle or filter out header keys with None values (or handle string conversions) rather than crashing with an AttributeError.

Actual Behavior

Traceback (most recent call last):
File "reproduce.py", line 9, in
conn._tunnel()
File "/usr/lib/python3.10/http/client.py", line 936, in _tunnel
value_bytes = value.encode("latin-1")
AttributeError: 'NoneType' object has no attribute 'encode'

CPython versions tested on:

3.10

Operating systems tested on:

Linux

Linked PRs

According to https://devguide.python.org/versions/, Python 3.10 has reached EOL

Yes, Python 3.10 went EOL last week, so unfortunately, we can't change anything there. This does affect recent versions, though, since the regressing change (#146212) was backported to other versions, so we could potentially fix it in those.

That said, _tunnel is a private method, so you opt in to these sorts of breakages by using it. Do you have any data on how widespread the breakage is here (not just libraries that pass None to headers, but libraries that call _tunnel)? Or, ideally, a repro that doesn't use private APIs?

Is the desired behavior to not raise any exception? I think passing None qualifies as an "ilegal" header/value name and thus must raise the same error:

ValueError: Invalid header name None

Thank you for the quick and helpful response!

1. Minimal Repro Using Public APIs (`connect()`)

Here is a minimal reproduction using only public APIs (set_tunnel and connect). No private methods like _tunnel() are called directly:

import http.client

conn = http.client.HTTPSConnection("127.0.0.1", 8080)

conn.set_tunnel("example.com", 443, headers={"X-Test-Header": None})

try:
    conn.connect()
except AttributeError as e:
    print(f"Caught expected AttributeError: {e}")

2. Real-World Context: Unauthenticated Proxies & Widespread Breakage

This issue breaks real-world CLI tools and applications such as Apache Thrift (THttpClient).

In practice, this commonly happens when configuring an HTTP proxy without user credentials via environment variables:

export http_proxy="http://YOUR_PROXY_HOST:PORT"

Libraries like Apache Thrift (THttpClient.flush()) construct request/tunnel headers dynamically.
When proxy authentication (username/password) or session credentials are not provided, these libraries set the corresponding header values to None (e.g. {"Proxy-Authorization": None} or unset auth token headers) and pass the dictionary to set_tunnel(..., headers=...).
Standard high-level operations (e.g., logging in, running analysis commands) trigger conn.connect(), which internally calls _tunnel() and crashes with:
AttributeError: 'NoneType' object has no attribute 'encode'

Users encounter this failure simply by running standard CLI commands on unauthenticated proxy networks after upgrading Python.

3. Previous Behavior vs. Desired Behavior

Regarding whether None should raise a ValueError:

Previous Behavior (Python 3.10.20 and earlier):
Passing None as a header value did not raise an exception. Requests and handshakes through unauthenticated proxies worked seamlessly across numerous releases.
Current Behavior (Python 3.10.21):
The handshake immediately fails with AttributeError: 'NoneType' object has no attribute 'encode'.
Desired Behavior:
If Python strictly treats None as an illegal value and raises ValueError: Invalid header name/value None, it will still break existing real-world libraries and proxy setups that previously worked without issue.

For backwards compatibility, the most practical and helpful behavior would be:
- Silently ignore / skip headers whose value is None (treating them as omitted/unset), or
- Tolerate None values during tunnel header serialization so that unauthenticated proxy configurations do not break.

I'd appreciate it if you avoided responding via LLMs -- it's much more meaningful to use your own words!

Anyway, thanks for the repro. Has this been reported elsewhere? I can't find any reports of this on Thrift or CodeChecker's issue trackers. (We can probably fix it on 3.14; it's just a question of whether it's worth asking the RMs for backports to older versions, since this resulted from a security fix.)

Hi! I'm new to the CPython community and looking for a first issue to contribute to.. I think this one might be a good fit. What do you think? Is anyone already working on a fix?
Looking at the existing code in _tunnel(), the pattern for invalid headers already raises ValueError -- so I was thinking of adding a check before calling .encode() to raise ValueError when a header value is None.
Would that be the right approach, or would you prefer to silently skip None values for backwards compatibility?

IIRC, empty HTTP headers are technically valid under the spec.
I think both ignoring None values and the current error might have unintended consequences. I think a good middle ground is to send them empty and avoid calling .encode() in those cases.
Although I think this could require more discussion

Yeah, this needs more discussion, but feel free to submit a fix once we've reached consensus. I'd personally like to see some concrete examples of where this causes breakage; a minimal snippet using a third-party library that worked in 3.14.x and no longer works in 3.14.x+1 would be very convincing.

After a bit more exploration, I found that setting any non-string value causes the same issue:

>>> import http.client
>>> conn = http.client.HTTPSConnection("127.0.0.1", 8080)
>>> # Value: None
>>> conn.set_tunnel("example.com", 443, headers={"X-Test-Header": None})
>>> conn._tunnel()
Traceback (most recent call last):
  File "<python-input-3>", line 1, in <module>
    conn._tunnel()
    ~~~~~~~~~~~~^^
  File "C:\Users\eduardovil\Development\Python\cpython\Lib\http\client.py", line 1016, in _tunnel
    value_bytes = value.encode("latin-1")
                  ^^^^^^^^^^^^
AttributeError: 'NoneType' object has no attribute 'encode'
>>> # Value: Int
>>> conn.set_tunnel("example.com", 443, headers={"X-Test-Header": 10})
>>> conn._tunnel()
Traceback (most recent call last):
  File "<python-input-5>", line 1, in <module>
    conn._tunnel()
    ~~~~~~~~~~~~^^
  File "C:\Users\eduardovil\Development\Python\cpython\Lib\http\client.py", line 1016, in _tunnel
    value_bytes = value.encode("latin-1")
                  ^^^^^^^^^^^^
AttributeError: 'int' object has no attribute 'encode'
>>> # Value: string representable
>>> class User:
...     def __str__(self):
...         return "user@example.com"
...
>>> conn.set_tunnel("example.com", 443, headers={"X-Test-Header": User()})
>>> conn._tunnel()
Traceback (most recent call last):
  File "<python-input-8>", line 1, in <module>
    conn._tunnel()
    ~~~~~~~~~~~~^^
  File "C:\Users\eduardovil\Development\Python\cpython\Lib\http\client.py", line 1016, in _tunnel
    value_bytes = value.encode("latin-1")
                  ^^^^^^^^^^^^
AttributeError: 'User' object has no attribute 'encode'

I think we could:

Leave it as is - perhaps omit None headers
Return a different exception when people try to input a non-string value, more clearly explaining the issue (current traceback is not very intuitive on what to do next)
Attempt to convert values to strings (maybe have a special case where None becomes '')

@ZeroIntensity

Hey everyone! I did some digging and wanted to share what I found.

Root cause

This was introduced in #146212 (05ed7ce7ae9) as a fix for gh-146211 (HTTP CONNECT tunneling didn't sanitize CR/LF in headers). The fix was backported to 3.10–3.14. It replaced:

# before -- f-string coerces value via str() implicitly
headers.append(f"{header}: {value}\r\n".encode("latin-1"))

with:

# after -- value must already be str
header_bytes = header.encode("latin-1")
value_bytes  = value.encode("latin-1")   # crashes if value is not a string

Apache Thrift with unauthenticated proxy

Here’s the full code: thrift/transport/THttpClient.py:

__init__ -- proxy_auth is set from basic_proxy_auth_header():

self.proxy_auth = self.basic_proxy_auth_header(parsed)

basic_proxy_auth_header -- returns None when the proxy has no credentials:

@staticmethod
def basic_proxy_auth_header(proxy):
    if proxy is None or not proxy.username:
        return None   # unauthenticated proxy: no username => None
    ...

open -- passes self.proxy_auth (now None) directly to set_tunnel:

self.__http.set_tunnel(self.realhost, self.realport,
                       {"Proxy-Authorization": self.proxy_auth})

So any HTTPS request through an unauthenticated proxy ends up calling set_tunnel(..., {"Proxy-Authorization": None}), which crashes when _tunnel() calls None.encode("latin-1").

Before this change, the f-string silently coerced None to "None", so Thrift was sending Proxy-Authorization: None in the CONNECT.

That is a latent bug in Thrift -- for an unauthenticated proxy the header should not be sent -- but proxies tend to ignore unrecognised auth values, so it worked in practice.

Worth opening an issue on the Thrift side too, which would also answer @ZeroIntensity's question about whether this has been reported before or not.

Reproducing

@ZeroIntensity asked for a minimal snippet using a third-party library.

pip install thrift is the only dependency. This is reproducer.py:

import os, socket, ssl, threading
from thrift.transport import THttpClient

def accept_one(srv):
    conn, _ = srv.accept()
    conn.recv(4096)
    conn.sendall(b'HTTP/1.1 200 Connection established\r\n\r\n')
    conn.recv(4096)
    conn.close()

srv = socket.socket()
srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
srv.bind(('127.0.0.1', 0))
srv.listen(1)
threading.Thread(target=accept_one, args=(srv,), daemon=True).start()

os.environ['https_proxy'] = f'http://127.0.0.1:{srv.getsockname()[1]}'

transport = THttpClient.THttpClient('https://example.com/api')
transport.write(b'hello')
try:
    transport.flush()
except AttributeError as e:
    print(f'REGRESSION: {e}')
except ssl.SSLError:
    # The fake server accepts the CONNECT and responds 200, but doesn't speak
    # SSL -- so the handshake fails here. This means _tunnel() succeeded and
    # the regression isn't present.
    print('OK -- tunnel established (SSL failed on fake server, expected)')

Tested across versions with Docker:

for tag in 3.12.13-slim 3.12.14-slim 3.13.13-slim 3.13.14-slim 3.14.4-slim 3.14.5-slim 3.15-rc-slim; do
    echo -n "python:$tag  =>  "
    docker run --rm \
        -v "$(pwd)/reproducer.py:/reproducer.py" \
        python:$tag \
        sh -c "pip install thrift -q --root-user-action=ignore && python /reproducer.py"
done

Version	Result
3.12.13	OK
3.12.14	`AttributeError: 'NoneType' object has no attribute 'encode'`
3.13.13	OK
3.13.14	`AttributeError: 'NoneType' object has no attribute 'encode'`
3.14.4	OK
3.14.5	`AttributeError: 'NoneType' object has no attribute 'encode'`
3.15-rc (3.15.0rc3)	`AttributeError: 'NoneType' object has no attribute 'encode'`

Fix approaches and their impact

As @edvilme noted, this affects any non-str value. I tested four approaches on Python 3.12.14:

Skip None -- omit the header when the value is None. This is new behavior, but it seems semantically correct to me for the unauthenticated-proxy case.
```
if value is None: continue
```
Result: OK -- tunnel established
ValueError on None -- raise explicitly instead of crashing with AttributeError. Thrift still breaks, just with a clearer error.
```
if value is None: raise ValueError(...)
```
Result: ValueError: Invalid tunnel header value None for header 'Proxy-Authorization'
None => "" -- sends Proxy-Authorization: (empty value) in the CONNECT. It works, but it seems semantically wrong to me: we'd still be sending an auth header, but there are no credentials.
```
if value is None: value = ""
```
Result: OK -- tunnel established
str(value) -- restores the previous behavior: None => "None", 42 => "42", any object => its __str__. This is the closest to the old behavior, but tools like Thrift would still keep sending the header Proxy-Authorization: None.
```
if not isinstance(value, str): value = str(value)
```
Result: OK -- tunnel established

What do you think? Happy to open a PR once there’s consensus on the approach :D

I think we should convert to str either way

As for the None value, I think that would require different considerations as to (1) omit, (2) error, (3) convert to "None", (4) convert to ""

I would lean towards 3 if it matches old behavior the closest (my opinion, not a core dev), but perhaps you could open an issue on discuss.python.org to get more exposure and opinions:)

Agreed on converting to str in general, that restores the old behavior for ints and other objects.

For None I'd lean towards (1) omit, but that's only the way I see it and, as I said, I'm new to the community.

With (3) we keep sending Proxy-Authorization: None, and with (4) we'd still send an auth header, just with an empty value. Omitting it matches what the caller actually means: "there is no value for this header". I think that's how requests treats a header set to None.

It would be simple: skip the header if the value is None, otherwise str(value) and then the CR/LF check as today.

I've never opened a thread on discuss.python.org, but I'm happy to do it if you think that's needed. This is my first contribution here and I'm really glad to help :D

I also agree that it’s important to preserve the current behavior so we don’t introduce a breaking change for existing users of this API and to keep it stable. That’s why I like the idea of returning "None" as a string.

That said, since Python is a language built for the future, it would be more versatile and more appropriate to follow industry standards and return null, that is, a proper None.

The first option benefits people who already depend on this behavior, while the second benefits those who will adopt it later. Out of respect for current users, we could emit a deprecation warning announcing the change and then make it effective after a transition period. That way, everyone is happy.

@bielpieroli

Just to clarify, I'm working with @bielpieroli, and as suggested to him by @edvilme, I started a discussion topic. If you'd like to follow the discussion, it's here.

I think we should just str() both the key and the value, since that's what the previous behavior was. It should be as simple as:

diff --git a/Lib/http/client.py b/Lib/http/client.py
index 4b6fc549a9b..12525a7c897 100644
--- a/Lib/http/client.py
+++ b/Lib/http/client.py
@@ -1014,8 +1014,8 @@ def _tunnel(self):
             self._http_vsn_str.encode("ascii"))
         headers = [connect]
         for header, value in self._tunnel_headers.items():
-            header_bytes = header.encode("latin-1")
-            value_bytes = value.encode("latin-1")
+            header_bytes = str(header).encode("latin-1")
+            value_bytes = str(value).encode("latin-1")
             if not _is_legal_header_name(header_bytes):
                 raise ValueError('Invalid header name %r' % (header_bytes,))
             if _is_illegal_header_value(value_bytes):

It'd also be nice if we explicitly documented that the headers are converted to a string.

This is a private API. Why are people even using it, and why are we considering providing support for such usage? If we want to make it supported usage, let's expose a new, official method (which can simply be called tunnel) and give it whatever semantics make the most sense for future users. Existing users can continue to use the private method (working around its limitations and quirks as needed) until they can transition to the new, supported one.

Calling .connect() with tunnels set internally calls the private method, so the bug is present in regular case scenarios and even with 3rd party libraries

pythongh-159044: Fix http.client tunnel headers with non-string values

I had Codex track down libraries that are affected and I came up with a script to reproduce it:

Details

# /// script
# dependencies = [
#     "thrift==0.23.0",
#     "pyhive==0.7.0",
#     "impyla==0.24.0",
#     "impala-shell==4.6.0",
#     "codechecker==6.29.1",
# ]
#
# [[tool.uv.dependency-metadata]]
# name = "impala-shell"
# version = "4.6.0"
# requires-dist = ["six==1.17.0", "thrift==0.23.0"]
# ///

import os
import socket
from contextlib import contextmanager


@contextmanager
def try_library(name):
    try:
        yield
    except AttributeError:
        print(name, "is affected!")


with socket.create_server(("127.0.0.1", 0)) as proxy:
    os.environ["https_proxy"] = f"http://127.0.0.1:{proxy.getsockname()[1]}"
    os.environ["no_proxy"] = ""

    with try_library("thrift"):
        from thrift.transport.THttpClient import THttpClient

        THttpClient("https://example.invalid/api").flush()

    with try_library("pyhive"):
        from pyhive import hive

        hive.connect(host="example.invalid", port=443, scheme="https", username="test")

    with try_library("impyla"):
        from impala.dbapi import connect

        connect(
            host="example.invalid",
            port=443,
            use_http_transport=True,
            use_ssl=True,
            http_path="cliservice",
            timeout=1,
            retries=1,
        ).cursor()

    with try_library("impala_shell"):
        from impala_shell.ImpalaHttpClient import ImpalaHttpClient

        ImpalaHttpClient("https://example.invalid/api").open()

    with try_library("CodeChecker"):
        from codechecker_client.helpers.authentication import ThriftAuthHelper

        client = ThriftAuthHelper("https", "example.invalid", 443, "/v6/Authentication")
        client.getAuthParameters()

So, concretely, (at least) all of the following are affected:

But, I couldn't find any reports on their issue trackers, so I guess this has just gone unnoticed so far.

gh-159044: Restore string conversion for HTTP tunnel header values (G…

[3.14] gh-159044: Restore string conversion for HTTP tunnel header va…

[3.15] gh-159044: Restore string conversion for HTTP tunnel header va…

Navigation Menu

Repository navigation

`http.client.HTTPSConnection._tunnel` raises `AttributeError: 'NoneType' object has no attribute 'encode'` when header value is `None` #159044

Bug report

Bug Description

Target Python Version

Operating System

Code to Reproduce

Expected Behavior

Actual Behavior

CPython versions tested on:

Operating systems tested on:

Linked PRs

1. Minimal Repro Using Public APIs (`connect()`)

2. Real-World Context: Unauthenticated Proxies & Widespread Breakage

3. Previous Behavior vs. Desired Behavior

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

http.client.HTTPSConnection._tunnel raises AttributeError: 'NoneType' object has no attribute 'encode' when header value is None #159044

Description

Bug report

Bug Description

Target Python Version

Operating System

Code to Reproduce

Expected Behavior

Actual Behavior

CPython versions tested on:

Operating systems tested on:

Linked PRs

Activity

edvilme commented on Oct 9, 2026

ZeroIntensity commented on Oct 9, 2026

edvilme commented on Oct 9, 2026

gaio-kimura commented on Oct 9, 2026

1. Minimal Repro Using Public APIs (connect())

2. Real-World Context: Unauthenticated Proxies & Widespread Breakage

3. Previous Behavior vs. Desired Behavior

ZeroIntensity commented on Oct 9, 2026

bielpieroli commented on Oct 9, 2026

edvilme commented on Oct 9, 2026

ZeroIntensity commented on Oct 10, 2026

edvilme commented on Oct 10, 2026

bielpieroli commented on Oct 10, 2026

edvilme commented on Oct 10, 2026

bielpieroli commented on Oct 10, 2026

LorenaMBorges commented on Oct 10, 2026

LorenaMBorges commented on Oct 10, 2026

ZeroIntensity commented on Oct 11, 2026

pfmoore commented on Oct 11, 2026

edvilme commented on Oct 11, 2026

ZeroIntensity commented on Oct 12, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

`http.client.HTTPSConnection._tunnel` raises `AttributeError: 'NoneType' object has no attribute 'encode'` when header value is `None` #159044

1. Minimal Repro Using Public APIs (`connect()`)