The Fix
pip install urllib3==1.26.6
Based on closed urllib3/urllib3 issue #1062 · 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%.
@@ -1,6 +1,19 @@
=======
+
+2.0.0 (unreleased)
+------------------
repro.py
import urllib3
http = urllib3.PoolManager()
http.request(
"POST",
"http://localhost:5000/",
fields={"file": ("ski ⛷.txt", b"value")},
)
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.6\nWhen NOT to use: This fix should not be applied if backward compatibility with legacy systems is a priority.\n\n
Why This Fix Works in Production
- Trigger: When sending files to a server that does not understand "filename*" parameters inside the Content-Disposition header, the server will fail to find the file…
- Mechanism: The Content-Disposition header was missing the 'filename' parameter when 'filename*' was present
- Why the fix works: Aligns multipart header formatting with the current WHATWG HTML Standard, ensuring both 'filename' and 'filename*' parameters are handled correctly. (first fixed release: 1.26.6).
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
- The Content-Disposition header was missing the 'filename' parameter when 'filename*' was present
- Production symptom (often without a traceback): When sending files to a server that does not understand "filename*" parameters inside the Content-Disposition header, the server will fail to find the file name because the "filename" parameter is not also included.
Proof / Evidence
- GitHub issue: #1062
- Fix PR: https://github.com/urllib3/urllib3/pull/2257
- First fixed release: 1.26.6
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.75
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.68
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“So, we could definitely do this: we could aim to do so by encoding using an 'ignore' or 'replace' mode on the encoder”
“Please note that cgi.FieldStorage doesn't support filename* form (in Python 2 at least), so all servers using the standard library's cgi module are actually broken.…”
“@sprat Pull requests to rectify this would be happily reviewed and accepted. Complaining gets us nowhere. Feel free to send a pull request to fix…”
“Started doing some research”
Failure Signature (Search String)
- When sending files to a server that does not understand "filename*" parameters inside the Content-Disposition header, the server will fail to find the file name because the
- – Include a "filename*" parameter where the desired filename cannot be expressed faithfully using the "filename" form. Note that legacy user agents will not process this, and
Copy-friendly signature
signature.txt
Failure Signature
-----------------
When sending files to a server that does not understand "filename*" parameters inside the Content-Disposition header, the server will fail to find the file name because the "filename" parameter is not also included.
– Include a "filename*" parameter where the desired filename cannot be expressed faithfully using the "filename" form. Note that legacy user agents will not process this, and will fall back to using the "filename" parameter's content.
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
When sending files to a server that does not understand "filename*" parameters inside the Content-Disposition header, the server will fail to find the file name because the "filename" parameter is not also included.
– Include a "filename*" parameter where the desired filename cannot be expressed faithfully using the "filename" form. Note that legacy user agents will not process this, and will fall back to using the "filename" parameter's content.
Minimal Reproduction
repro.py
import urllib3
http = urllib3.PoolManager()
http.request(
"POST",
"http://localhost:5000/",
fields={"file": ("ski ⛷.txt", b"value")},
)
What Broke
File uploads failed to work correctly due to missing filename information.
Why It Broke
The Content-Disposition header was missing the 'filename' parameter when 'filename*' was present
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install urllib3==1.26.6
When NOT to use: This fix should not be applied if backward compatibility with legacy systems is a priority.
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/2257
First fixed release: 1.26.6
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be applied if backward compatibility with legacy systems is a priority.
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.
Version Compatibility Table
| Version | Status |
|---|---|
| 1.26.6 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.