A file downloads through your CDN and passes its integrity check, but its saved name is an object ID, garbled text, or an outdated filename. Investigate the response metadata and the code initiating the download. File contents and suggested save names are handled separately, so refreshing the file alone may not fix naming.
This guide covers static downloads, object storage, and export endpoints. Commands use Bash and curl with example domains and paths; they have not been tested against your production environment. Inspect private exports only in an authorized test setup, and keep signed URLs and personal information out of support tickets.
Identify what initiates the save operation
Direct navigation, a link with a download attribute, and a fetch request followed by Blob creation can obtain their filenames from different places. In the browser's Network panel, record the final request, redirect chain, and response headers. Check whether front-end code explicitly supplies a name.
For a directly downloaded response, Content-Disposition can suggest a filename. Without a suitable suggestion, the browser may derive a name from the URL path or other information, exposing a random object-storage key in the save dialog. Browsers and operating systems also sanitize unsupported characters; the final name is not guaranteed to match the header byte for byte.[1]
The HTML download attribute primarily applies to same-origin URLs and blob: or data: URLs. Do not rely on it alone to force a name for a cross-origin CDN link. Response headers and browser download policies also affect the result.[2]
Inspect the final GET response, not just the first redirect
Use a small public test file that you are permitted to download:
curl -sS -L --max-redirs 5 --max-time 30 \ -D download-headers.txt -o downloaded-test.bin \ https://downloads.example.com/files/report.pdf
This command saves the body under a fixed local test name so you can inspect the headers independently. It does not reproduce the browser's complete naming behavior. It downloads the response body, so avoid large files or export endpoints with side effects. On Windows, use curl.exe where necessary and adapt the line-continuation syntax.
The header file may contain several responses. Inspect the final response carrying the download, including Content-Disposition, Content-Type, status, cache-status headers, and Age. An attachment header on an earlier redirect does not replace the header on the actual file response. A login page or error JSON returned with 200 can also be mistaken for a file.
HEAD is useful for an initial comparison, but an application may handle HEAD and GET differently. A range GET can take a different cache path too. Validate the real download before concluding that the issue is fixed.
Use filename* for UTF-8 names and keep an ASCII fallback
A common response header pattern is:
Content-Disposition: attachment; filename="report-2026.pdf"; filename*=UTF-8''%E6%8A%A5%E5%91%8A-2026.pdf Content-Type: application/pdf
Here filename supplies an ASCII fallback. The filename* parameter uses percent-encoded UTF-8 bytes for the Chinese name “报告-2026.pdf”. Clients supporting filename* generally prefer it; providing both improves compatibility with older clients.[1]
Do not put the same percent-encoded value into ordinary filename and expect consistent decoding across browsers. Do not URL-encode the whole Content-Disposition value either: that can damage its parameter structure, semicolons, and quotation marks. Prefer a mature header-building utility in your language or framework over manual string concatenation.
attachment suggests saving the response, whereas inline allows inline presentation. Neither converts an error response into a valid file. Keep the media type consistent with the actual content rather than assigning one MIME type to every response merely to trigger a download.
When a name originates in user input, remove CR/LF, path separators, control characters, and dangerous names; limit its length and choose the extension according to a trusted file type. Never insert unvalidated input into a response header or expose a server directory path as the suggested filename.
Compare origin metadata with what the CDN delivers
If the origin returns the correct name while the edge returns an old one, check object-storage metadata, reverse proxies, edge functions, and response-header policies. Multiple layers appending Content-Disposition can produce duplicate or invalid values. Establish which layer owns the final naming decision.
From an environment authorized to access the origin, retain the URL hostname, TLS SNI, and certificate verification while selecting the connection target:
curl -sS --resolve downloads.example.com:443:203.0.113.10 \ --max-time 30 -D origin-headers.txt -o origin-test.bin \ https://downloads.example.com/files/report.pdf
The IP address is reserved for documentation. If the origin accepts only CDN traffic, use an approved diagnostic route. Do not expose it publicly or add -k to bypass certificate verification. Preserve equivalent access permissions and relevant request conditions so an authentication difference is not mistaken for caching.
A cached object can retain an outdated filename along with its headers. The effects of replacing content, updating metadata, or changing an edge policy depend on the platform. Confirm the real cache key, invalidate the affected file entry, and inspect the final headers with GET. Avoid a full-site purge by default because it can increase origin load.
Some object-storage services support signed query parameters that override download response headers. Feature availability and parameter names are provider-specific. Editing a signed parameter can invalidate the signature, while ignoring naming-related parameters in a CDN cache key can mix metadata. Do not apply one provider's example indiscriminately to another.
Review shared caching when names vary by language or user
If a single URL returns different filenames according to request language, explicitly determine whether the relevant request fields participate in cache variants. Vary alone does not guarantee every CDN will separate them as intended. Explicit language paths or stable versioned addresses may be easier to maintain.
User-specific exports need particular care. A name or order number can appear in the file body or only in Content-Disposition. Even when the binary contents are identical, shared response headers can leak information.
Adding a filename dimension to a cache key is not a complete security solution. Review authentication, cookies, Authorization, Cache-Control, and edge bypass rules together. Incorrect caching must not bypass signed-URL access validation.
For fetch downloads, check whether the script can read the header
After a cross-origin fetch succeeds, a script that reads Content-Disposition needs that response header exposed, for example:
Access-Control-Expose-Headers: Content-Disposition
This does not replace the underlying CORS permissions. Origin and credentials settings must still be correct. Do not rely on wildcard exposed-header behavior for credentialed requests; listing the required header explicitly is easier to audit.[3]
If the script creates a Blob URL and assigns a link's download attribute, its hard-coded string may determine the saved name. Updating the server header does not automatically update that front-end logic. Use reliable parsing for filename and filename*, including encoding, quoting, and fallback handling, rather than naïvely splitting every value at semicolons.
Reading a large file into a Blob can also increase memory use. Evaluate the current download design and target devices instead of moving every download into a complete in-memory Blob just to fix a name. Sanitize parsed names in the front end too; they are not trusted filesystem paths.
Verify in real browsers and preserve a rollback configuration
Before editing, save object metadata, application header settings, and CDN rules. Start with one test file and check ASCII names, non-ASCII names, and spaces. Then cover redirects, cache hits and misses, direct links, and script-driven downloads.
Save the file in the supported browsers and operating systems while checking its content checksum. A correct name does not prove the contents are correct, and correct contents do not prove metadata has not been mixed. For private downloads, also test account isolation and expired signatures.
For rollback, restore the last verified metadata or header policy and address the affected edge cache. Server-side changes cannot rename files already saved on a visitor's device. If notification is needed, explain which existing files remain valid and which need downloading again.
Keep the final GET headers, front-end naming source, cache-key conditions, and actual saved result in the incident record. Those details distinguish encoding errors, header overrides, stale metadata, and hard-coded client names.
References
Sources checked for the paired article on October 29, 2026. Consult your provider's documentation for object-storage response-header overrides and CDN cache policies.
