◆Error Codes Wiki

Content-Disposition Header Errors — File Download Naming and Handling Issues

Informational4xx client error

Overview

Fix Content-Disposition header errors causing incorrect file names, failed downloads, and improper inline vs attachment handling in browsers.

Key Details

  • Content-Disposition controls whether the browser displays content inline or prompts a file download
  • The 'attachment' disposition triggers a download with the specified filename
  • The 'inline' disposition displays content in the browser (e.g., PDFs, images)
  • Special characters and non-ASCII characters in filenames require RFC 5987 encoding
  • Different browsers handle Content-Disposition inconsistencies differently

Common Causes

  • Filename containing special characters (spaces, quotes, Unicode) not properly encoded
  • Missing Content-Disposition header causing browser to display binary content instead of downloading
  • Incorrect disposition type (inline when attachment was intended or vice versa)
  • CDN or proxy stripping or modifying the Content-Disposition header

Steps

  1. 1Set the header correctly: Content-Disposition: attachment; filename="report.pdf"; filename*=UTF-8''report.pdf
  2. 2Use RFC 5987 encoding for non-ASCII filenames: filename*=UTF-8''%E5%A0%B1%E5%91%8A.pdf
  3. 3For inline display, use Content-Disposition: inline; filename="document.pdf" with appropriate Content-Type
  4. 4Test across browsers — Chrome, Firefox, Safari, and Edge may handle edge cases differently
  5. 5Ensure CDN pass-through: configure your CDN to not strip or cache Content-Disposition headers

Tags

content-dispositiondownloadfilenameattachmentinline

More in 4xx Client Error

http-400-bad-requestHTTP 400 Bad Request — What It Means & How to Fix It
Error
http-401-unauthorizedHTTP 401 Unauthorized — What It Means & How to Fix It
Error
http-402-payment-requiredHTTP 402 Payment Required — What It Means & How to Fix It
Error
http-403-forbiddenHTTP 403 Forbidden — What It Means & How to Fix It
Error
http-404-not-foundHTTP 404 Not Found — What It Means & How to Fix It
Error
http-405-method-not-allowedHTTP 405 Method Not Allowed — What It Means & How to Fix It
Error

Frequently Asked Questions

Inline tells the browser to display the content directly (e.g., show a PDF in the browser). Attachment tells the browser to download the file and prompt a save dialog.