starlette response headers support custom encoding (Fix)

The Fix

Allows non Latin-1 filenames in FileResponse, resolving issues with encoding Chinese characters.

Based on closed Kludex/starlette issue #790 · 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%.

Open PR/Commit

@@ -7,7 +7,7 @@
 from email.utils import formatdate
 from mimetypes import guess_type
-from urllib.parse import quote_plus
+from urllib.parse import quote, quote_plus

fix.md

Option A — Apply the official fix\nAllows non Latin-1 filenames in FileResponse, resolving issues with encoding Chinese characters.\nWhen NOT to use: This fix is not applicable if the application does not handle non-Latin filenames.\n\n

Why This Fix Works in Production

Trigger: UnicodeEncodeError: 'latin-1' codec can't encode character '\u6708' in position 32: ordinal not in range(256)
Mechanism: Response headers were encoded using 'latin-1', causing issues with non-Latin characters

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

Response headers were encoded using 'latin-1', causing issues with non-Latin characters
Surfaces as: UnicodeEncodeError: 'latin-1' codec can't encode character '\u6708' in position 32: ordinal not in range(256)

Proof / Evidence

GitHub issue: #790
Fix PR: https://github.com/kludex/starlette/pull/792
Reproduced locally: No (not executed)
Last verified: 2026-02-11
Confidence: 0.70
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.79

Discussion

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

Jump to Sources Open on GitHub

“#792 only solves FileReponse,but it still a problem in streamreponse.”

@CyberQin · 2020-08-03 · source

Failure Signature (Search String)

UnicodeEncodeError: 'latin-1' codec can't encode character '\u6708' in position 32: ordinal not in range(256)

Error Message

Stack trace

error.txt

Error Message
-------------
UnicodeEncodeError: 'latin-1' codec can't encode character '\u6708' in position 32: ordinal not in range(256)

What Broke

Returning a FileResponse with a Chinese filename results in a UnicodeEncodeError.

Why It Broke

Response headers were encoded using 'latin-1', causing issues with non-Latin characters

Fix Options (Details)

Option A — Apply the official fix

Allows non Latin-1 filenames in FileResponse, resolving issues with encoding Chinese characters.

When NOT to use: This fix is not applicable if the application does not handle non-Latin filenames.

Fix reference: https://github.com/kludex/starlette/pull/792

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

When NOT to Use This Fix

This fix is not applicable if the application does not handle non-Latin filenames.

Did This Fix Work in Your Case?

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

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Related Issues

No related fixes found.

Cluster: starlette:configuration-error All hubs All clusters

Related clusters: Data consistency SSL handshake Other

Sources

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