The Fix
pip install requests==2.29.0
Based on closed psf/requests issue #6159 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -14,9 +14,11 @@
_VALID_HEADER_VALUE_RE_STR = re.compile(r"^\S[^\r\n]*$|^$")
+_HEADER_VALIDATORS_STR = (_VALID_HEADER_NAME_RE_STR, _VALID_HEADER_VALUE_RE_STR)
+_HEADER_VALIDATORS_BYTE = (_VALID_HEADER_NAME_RE_BYTE, _VALID_HEADER_VALUE_RE_BYTE)
HEADER_VALIDATORS = {
repro.py
from enum import Enum
import requests
class CustomEnum(str, Enum):
TRACE_ID = "X-B3-TraceId"
requests.get("http://URL", headers={CustomEnum.TRACE_ID: "90e85293-afd1-4b48-adf0-fa6daf02359e"})
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 requests==2.29.0\nWhen NOT to use: This fix should not be used if strict type enforcement for headers is required.\n\nOption B — Safe version pin\npip install requests==2.27.1\nWhen NOT to use: Do not use if you need features or security fixes in newer releases.\n\nOption C — Workaround\nfor us.\nWhen NOT to use: This fix should not be used if strict type enforcement for headers is required.\n\n
Why This Fix Works in Production
- Trigger: requests.get("http://URL", headers={CustomEnum.TRACE_ID: "90e85293-afd1-4b48-adf0-fa6daf02359e"})
- Mechanism: The requests library enforced stricter type checks for header keys, rejecting string enums
- Why the fix works: Allows str/bytes subclasses to be used as header parts, resolving the issue with InvalidHeader errors when using string enums as headers. (first fixed release: 2.29.0).
Production impact:
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Shows up under Python 3.8 in real deployments (not just unit tests).
- The requests library enforced stricter type checks for header keys, rejecting string enums
- Surfaces as: Traceback (most recent call last):
Proof / Evidence
- GitHub issue: #6159
- Fix PR: https://github.com/psf/requests/pull/6356
- First fixed release: 2.29.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.95
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.43
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“We encountered this same issue when passing header values whose type is a subclass of str. Might it make sense to allow subclasses to pass…”
“Here's another instance fwiw: https://github.com/taverntesting/tavern/issues/788 In this case it's just a subclass of str being passed in as header values: https://github.com/taverntesting/tavern/blob/ede36ca062b546cfaf3e6b0940fbac30733586a4/tavern/util/format”
“Just want to add support for this issue by saying we are also having this issue”
“> Using enums for header names is a common (and generally regarded as a good) practice”
Failure Signature (Search String)
- requests.get("http://URL", headers={CustomEnum.TRACE_ID: "90e85293-afd1-4b48-adf0-fa6daf02359e"})
Error Message
Stack trace
error.txt
Error Message
-------------
Traceback (most recent call last):
File "/home/yair/PycharmProjects/tests/requests_error.py", line 9, in <module>
requests.get("http://URL", headers={CustomEnum.TRACE_ID: "90e85293-afd1-4b48-adf0-fa6daf02359e"})
File "/home/yair/.local/lib/python3.8/site-packages/requests/api.py", line 73, in get
return request("get", url, params=params, **kwargs)
File "/home/yair/.local/lib/python3.8/site-packages/requests/api.py", line 59, in request
return session.request(method=method, url=url, **kwargs)
File "/home/yair/.local/lib/python3.8/site-packages/requests/sessions.py", line 573, in request
prep = self.prepare_request(req)
File "/home/yair/.local/lib/python3.8/site-packages/requests/sessions.py", line 484, in prepare_request
p.prepare(
File "/home/yair/.local/lib/python3.8/site-packages/requests/models.py", line 369, in prepare
self.prepare_headers(headers)
File "/home/yair/.local/lib/python3.8/site-packages/requests/models.py", line 491, in prepare_headers
check_header_validity(header)
File "/home/yair/.local/lib/python3.8/site-packages/requests/utils.py", line 1037, in check_header_validity
raise InvalidHeader(
requests.exceptions.InvalidHeader: Header part (<CustomEnum.TRACE_ID: 'X-B3-TraceId'>) from {<CustomEnum.TRACE_ID: 'X-B3-TraceId'>: '90e85293-afd1-4b48-adf0-fa6daf02359e'} must be of type str or bytes, not <enum 'CustomEnum'>
Minimal Reproduction
repro.py
from enum import Enum
import requests
class CustomEnum(str, Enum):
TRACE_ID = "X-B3-TraceId"
requests.get("http://URL", headers={CustomEnum.TRACE_ID: "90e85293-afd1-4b48-adf0-fa6daf02359e"})
Environment
- Python: 3.8
What Broke
Using string enums as headers resulted in InvalidHeader errors, causing request failures.
Why It Broke
The requests library enforced stricter type checks for header keys, rejecting string enums
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install requests==2.29.0
When NOT to use: This fix should not be used if strict type enforcement for headers is required.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Option B — Safe version pin Backward-compatible pin
pip install requests==2.27.1
When NOT to use: Do not use if you need features or security fixes in newer releases.
Use when you can’t upgrade immediately. Plan a follow-up to upgrade (pins can accumulate security/compat debt).
Option C — Workaround Temporary workaround
for us.
When NOT to use: This fix should not be used if strict type enforcement for headers is required.
Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.
Option D — Guard side-effects with OnceOnly Guardrail for side-effects
Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.
- Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
- Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
- Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.
Show example snippet (optional)
onceonly.py
from onceonly import OnceOnly
import os
once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)
# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..." # replace
key = f"stripe:webhook:{event_id}"
res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
return {"status": "already_processed"}
# Safe to execute the side-effect exactly once.
handle_event(event_id)
When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Fix reference: https://github.com/psf/requests/pull/6356
First fixed release: 2.29.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be used if strict type enforcement for headers is required.
- Do not use if you need features or security fixes in newer releases.
- Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
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 TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
- Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.
Version Compatibility Table
| Version | Status |
|---|---|
| 2.27.1 | Working |
| 2.29.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.