Broken Unicode download names: filename vs filename* in Content-Disposition
How to send a Unicode download name with Content-Disposition: an ASCII filename fallback, a UTF-8 filename* value, percent-encoded bytes, precedence, and safe handling under RFC 6266 and RFC 8187.
If a server intends 보고서.pdf but the suggested filename received is different or garbled, inspect the Content-Disposition response header. It tells a recipient how to handle the response and can suggest a local filename. Putting a non-ASCII name directly in plain filename may fail. For interoperability, RFC 6266 advises sending both filename and the extended filename* parameter.
attachment and the filename say different things
The attachment disposition tells the recipient to prompt for local saving rather than process the response normally. filename and filename* provide information for constructing the saved name.
Content-Disposition: attachment; filename="report.pdf"; filename*=UTF-8''%EB%B3%B4%EA%B3%A0%EC%84%9C.pdffilename="report.pdf" is an ASCII fallback for an older recipient that does not understand the extended syntax. filename* carries the intended name, 보고서.pdf. When both are present, RFC 6266 says a recipient that understands filename* should choose it and ignore filename. The fallback appears first, following the RFC’s interoperability advice.
Repeating a parameter name makes the field value invalid. This is not a format for listing several localized names in multiple filename* parameters. The language component is optional and has limited usefulness for filenames, so the example leaves it empty.
The starred value carries UTF-8 bytes
RFC 6266 cites RFC 5987 for this syntax, but RFC 8187 later obsoleted RFC 5987. The current encoding syntax therefore comes from RFC 8187. An extended value has the form charset'language'value. Producers must use UTF-8, and recipients must support UTF-8. Encoding 보고서.pdf produces these bytes:
EB B3 B4 EA B3 A0 EC 84 9C 2E 70 64 66ASCII characters allowed by the grammar stay as they are. Every other octet becomes % followed by two hexadecimal digits:
filename*=UTF-8''%EB%B3%B4%EA%B3%A0%EC%84%9C.pdfUTF-8 before the first apostrophe is the required charset. The optional language tag belongs between the apostrophes and is empty here. A space is not in attr-char, so it must become %20. Recipients must understand uppercase and lowercase hexadecimal digits, although consistent casing is easier to read.
This does not mean encoding an entire URL. It shares the conversion of UTF-8 octets to percent notation with URL percent-encoding, but here the governing syntax is an HTTP header parameter.
A received filename is advice, not a command
RFC 6266 stresses that recipients must treat the filename as advisory. A name such as ../../etc/passwd must not let a response write outside an authorized location; stripping everything except the final segment separated by \ or / is one possible defense. If a recipient relies on the extension to determine the media type, it must ensure the extension is safe, preferably one that matches the response media type. Control characters, surrounding whitespace, ., .., device names, and other names with special filesystem or shell meanings should be stripped or replaced.
A practical server default follows: put an ASCII filename fallback first, then the intended name encoded as UTF-8 in filename*. On the receiving side, validate the path and extension regardless of which parameter won. How browsers recover raw UTF-8 placed directly in plain filename is not guaranteed by these RFCs and is outside this article’s scope.
ZIP filename encoding covers the separate failure of names inside an archive after download.
Sources
Document status and errata were checked October 5, 2026.