Content-Disposition: Reliable and Safe Download Names

Content-Disposition tells a browser how content should be presented and can suggest a download filename. For a reliable export, set an intentional disposition, provide a safe filename and test international characters in the browsers your users rely on. Do not copy an untrusted path directly into the header.

This guide is about delivering generated files, not identifying their format. A filename is a usability hint; content type and safe handling still matter. A .csv extension does not transform arbitrary bytes into valid CSV.

Choose presentation deliberately

Content-Type: application/json
Content-Disposition: attachment; filename="report.json"

This simple example asks for download presentation and supplies a suggested name. The MDN Content-Disposition reference explains response behavior and parameters. Use the server framework's supported header utilities where possible.

inline and attachment express different presentation intent, but the browser and content type still influence the result. Test the actual response rather than promising that every client will behave identically.

Generate a filename from controlled parts

For recurring exports, use a stable prefix, a verified date and an extension matching the bytes. For example, a report name can be derived from an internal report type rather than a raw user title.

Reject control characters and path separators in user-supplied naming inputs. Avoid names that imply directories, special filesystem locations or another format. Apply a sensible length limit and provide a safe fallback when the proposed name becomes empty.

Do not use a full local path as the suggested filename. It can expose internal details and produce confusing behavior. The browser needs a name for the downloaded file, not the server's storage layout.

Support international names carefully

For non-ASCII filenames, use the standard extended filename mechanism where appropriate, often with an ASCII fallback for compatibility. Follow the framework or library's encoding behavior instead of manually concatenating a header string.

RFC 6266 defines the HTTP field and discusses filename handling. The important implementation decision is to keep the fallback and extended name consistent about the file's meaning and extension.

Test a name containing Japanese or Korean characters, spaces and ordinary punctuation. Verify the downloaded name, not just the header text. A browser may sanitize names for the local filesystem, so the final result can differ from the suggested value.

Do not confuse URL encoding with header construction

Percent-encoding is used in specific header syntax, but it is not a universal escape function for every parameter. Applying a generic URL encoder to the entire header can create an invalid value. Leaving reserved characters unescaped can also break parsing.

Use a library that implements the relevant header syntax. The URL Decoder can help inspect a synthetic encoded component during debugging; it does not construct or validate Content-Disposition headers.

Keep the original proposed name and the final safe name separate in code. That makes tests clearer and avoids accidentally using the original unvalidated value in a different response path.

Verify bytes and headers together

For a JSON export, parse the downloaded file and compare its expected record count. Inspect a small sanitized fixture using JSON Viewer. For CSV, use CSV Viewer to check the intended columns and quoting.

Confirm Content-Type, disposition and filename extension agree. A static host may return an HTML error page with a report-like filename; the download action alone is not proof that the export succeeded. Check status and content before offering it as a completed artifact.

For public export endpoints, HTTP Header Checker can review response headers. For private exports, use an authorized client and avoid sending session-bound URLs to a public lookup service.

Include proxy and cache behavior

A CDN or reverse proxy can change headers or cache a response with the wrong filename. Verify the deployed endpoint and its access policy. A user-specific export should not become a shared cached download merely because its path looks static.

If the export is stored in object storage, review metadata set at upload and response overrides used at download. A correct application header does not help if the browser is redirected to an object whose metadata says something else.

Keep signed download URLs free of unnecessary personal filename details when possible. URL query strings can be logged in multiple places. Do not expose internal account names solely to make the suggested file name more descriptive.

A small compatibility test matrix

Test an ASCII name, an international name, an empty proposed name, a long name and a rejected control-character input. Include browsers and operating systems used by the product. Confirm that a rejected naming input produces a safe error or fallback, not a malformed response.

Test the complete export workflow after deployment: permission check, generation, HTTP response and saved file. This catches problems that a unit test of the filename function cannot see.

Make downloads predictable

Generate safe names, use the correct header syntax and verify the delivered bytes. A reliable download is a complete file with an understandable name and an appropriate access boundary, not just a button that opens a save dialog.