Skip to content

Your article downloads as a file: check Content-Disposition

Find attachment headers or download attributes that turn an HTML page into a download, repair the owning rule, and verify direct visits and links separately.

By Crawlito · 5 min read

In short

  • Content-Disposition can ask a browser to download a response instead of displaying it inline.
  • A direct visit and a link with a download attribute can behave differently.
  • Fix the response or link owner without relabeling an unrelated file as HTML.
On this page

If an article downloads as a file instead of opening as a page, inspect Content-Disposition, Content-Type, and the link used to reach it. An attachment header or download-oriented link can change the browser experience even when the URL and response body look correct. Repair the owning rule and verify both direct navigation and the original link.

Do not assume this symptom means the article is absent from every search system. First establish the actual delivery behavior and what readers receive.

Open the article URL directly in a fresh browser session. Then follow the link that caused the download. Record whether both paths behave the same way.

Inspect the link markup for a download attribute and the actual resolved destination. A button labeled “Read guide” may point to an export endpoint rather than the page.

MDN's Content-Disposition reference describes inline and attachment handling. It also discusses interactions with HTML download links in supported browser contexts.

The distinction matters because changing a server header may not be the right repair for a link intentionally requesting a download.

Save the exact URL, link markup, response headers, and downloaded filename. These identify the boundary that changed the experience without requiring a broad rewrite of the page.

Inspect the public response and file type

Fetch the URL with GET:

bash
curl -sS -L -D article-headers.txt -o article-response.bin \
  'https://www.example.com/guides/setup'
file article-response.bin

Read the final response headers after redirects. Look for an attachment disposition and inspect the actual body.

An illustrative mismatch is:

http
Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="setup.html"

Those headers describe HTML delivered with download-oriented disposition. Whether that is a defect depends on the route's intended purpose.

If the body is actually a PDF, JSON export, or error message, do not relabel it as HTML to force a browser display. Fix the route or link so the reader reaches the intended article.

The content-type guide explains why metadata and bytes must agree.

Find where the disposition is added

Check the application response, object storage metadata, reverse proxy rules, and CDN response transformations. The public header may be added outside the article template.

Compare a working article on the same platform. If every object in one storage prefix downloads, inspect the rule or metadata applied to that prefix.

A migration may copy a download header from a document bucket into a page-hosting path. A generic response helper may also set attachment for both exports and normal pages.

Record the source of the header rather than editing the first configuration file you find. A local application change will not help if the CDN overwrites it.

Use a small ownership map:

ComponentPossible responsibility
Link templateDownload attribute or wrong endpoint
ApplicationResponse disposition
Storage objectSaved metadata
Proxy or CDNHeader override
Browser stateCached older response

The goal is to change the layer that actually produces the observed public behavior.

Repair the intended route without breaking downloads

For a normal article route, remove the unintended attachment behavior through the platform's supported mechanism. Keep an accurate HTML content type.

For a legitimate download route, preserve its download behavior and fix the link label or destination if the wrong route was advertised as an article.

Do not remove disposition headers from every resource globally. Reports, exports, and user-requested files may intentionally download with useful filenames.

If object metadata is the owner, update the approved public object and refresh the affected delivery cache as needed. If a shared response helper is responsible, separate page responses from file exports.

Keep the correction scoped to the actual content family. Test one normal article and one intentional download as controls.

The HTTP request guide helps avoid clearing the issue with a HEAD response when the browser's real GET still behaves differently.

Verify the original reader journey

After deployment, follow the exact original link in a fresh session. Confirm the page opens normally and displays the expected title, main explanation, and next step.

Then open the URL directly and fetch its headers again. The link and direct visit should now follow the intended contract.

Check another browser or supported device if the symptom was browser-specific. Do not assume identical handling across all clients based on one result.

Use a short acceptance record:

Article link: opens the intended page.
Direct article URL: displays the intended HTML.
Public headers: match the page's purpose.
Intentional export: still downloads correctly.
Cached old response: no longer served on the normal path.

A successful status code is not enough. The repair is complete when the reader receives the intended experience and content.

Inspect the canonical URL, sitemap entry, archive link, and social link for the affected article. They should point to the public page rather than a temporary export endpoint.

If the article and downloadable version both exist, make their roles clear. A useful HTML introduction can explain the document, while a labeled download link serves the file.

The PDF guide covers public documents as resources in their own right. The point is not to replace every download with HTML, but to avoid advertising one resource while delivering another.

Do not infer that changing disposition alone guarantees indexing or citations. Search and AI systems may process resources differently from a browser, and their later behavior needs separate evidence.

Report the observed before and after response, with the relevant headers and content marker, rather than a broad claim that all SEO problems are fixed.

Prevent metadata from drifting during publication

Review how storage uploads and response helpers assign headers. A default intended for private exports can be inappropriate for public pages.

Test the next new article or asset through the normal publishing workflow. A manual repair to one object does not prove future uploads inherit the right metadata.

If a CDN rule matches by extension or path prefix, include an example near that boundary. A route without .html may still serve HTML and should not be classified solely by its filename.

Document the intended behavior for pages and downloads in the deployment handoff. This helps infrastructure changes preserve the content team's expectations.

For a migration, include both kinds of resources in the release sample. A homepage-only check can miss a download rule applied to the rest of the content library.

Treat an incorrect suggested filename as a separate symptom from a page that downloads unexpectedly. A response can have the intended attachment behavior while supplying a confusing filename, or have a sensible filename while using the wrong disposition for an article. Record both observations rather than assuming they have one cause.

Check a second ordinary content page and one intentional download before broadening the repair. If a shared rule sets attachment headers across an entire folder, the comparison helps identify the affected scope. If only one uploaded object carries the header, review its stored metadata and publishing history. After changing that metadata, fetch the public URL again; inspecting the storage console alone does not prove that a cached response now carries the new value. Keep the successful header capture with the release note.

Frequently asked questions

Is Content-Disposition the same as Content-Type?

No. Content-Type describes the representation's format; disposition can influence how the browser presents or downloads it.

Inspect the link's destination and download attribute. The link can request a different experience from direct navigation.

Should every public file use inline disposition?

No. Choose behavior that matches the resource and reader task. Intentional downloads are legitimate.

Run the repaired article URL through the free Crawlito check after verifying the browser journey.

Filed under Access and robots.txt. Topics: http-status, html, troubleshooting