Downloading HTML Instead of PDF: Find the Cause

You click “Download instructions” and receive a guide.pdf file, but your viewer reports that it is damaged. Renaming it does not help: it may contain a sign-in page or an error message. Downloading HTML instead of PDF should be investigated as a response chain, not a file-extension problem. This training scenario needs a small public test document without personal data. We will separate three questions: which address was requested, what the server returned and how the browser was asked to name the result. This is not a client incident or a command for changing live hosting.

Start with the request that actually produces the file

In your browser, open developer tools and the Network tab before clicking the link. Find the document or download request, not the button image. Record the initial URL, method, status, any redirect and the final address. Do not copy cookies, authorization headers or signed links into a shared chat: they may grant access to a private document. Replace those values with [REDACTED] in a shared record.

If the address leads to a sign-in form, investigate access and link expiry first. If ordinary HTML comes back with status 200 instead of the document, transport success does not confirm the correct file. Conversely, refusal without authorization does not prove a fault: a protected download may correctly require an active session. Compare equivalent scenarios, not an authenticated browser with a client that has no session.

Save headers separately from the received bytes

Independent diagnosis requires a Linux or macOS terminal and curl. No administrator privileges or third-party packages are needed. First run curl --version: stopping a download of initially unknown size at the limit below requires curl 8.4.0 or later. In older releases, that protection does not apply when the size is unknown in advance. Do not install an update on a production server just for this exercise; use a prepared test computer.

Move into a separate empty local directory. The following command creates or overwrites the two named files there: make sure they contain no data you need. The downloads.example.test domain and guide.pdf path are examples, so replace the entire address with a known, authorized test download. Do not use an operation URL that creates an order or changes data. The command makes a GET request and limits its duration to twenty seconds and its size to one mebibyte; choose a smaller document for this exercise.

curl --silent --show-error --max-time 20 \
  --max-filesize 1048576 \
  --dump-header response-headers.txt \
  --output response.bin \
  'https://downloads.example.test/guide.pdf'

The --dump-header option writes the headers, while --output saves the body under a controlled local name. Redirects are deliberately not followed automatically, so the initial response is not lost. Check curl’s messages and exit status before drawing conclusions. If the size limit or timeout interrupts the transfer, response.bin may be incomplete; that does not prove the server’s document is damaged. The official curl documentation explains the precise option behaviour.

Compare the type, name and actual contents

Open response-headers.txt as text. For the training scenario of downloading a PDF, the expected fields might look like this. These are example headers, not Nginx or Apache configuration and not a result from checking your website:

Content-Type: application/pdf
Content-Disposition: attachment; filename="guide.pdf"

Content-Type describes the representation’s type. Content-Disposition with attachment suggests a download and filename. These fields have different roles: changing filename does not turn HTML into PDF. The inline value instead allows display in the browser. RFC 6266 defines filename handling; filename* is available for non-ASCII names. This exercise deliberately uses a simple ASCII name to avoid mixing content diagnosis with filename encoding.

Do not execute the received file or rename it as an executable. Inspect the beginning of response.bin in an editor that can safely display bytes. HTML markup containing sign-in or error text is strong evidence of a different response. A PDF signature alone does not prove that a document is complete or safe either. Compare the result with a known-good test file and check opening it only with a trusted tool in a test environment. Do not upload private documents to third-party online checkers.

Fix the confirmed cause, not just the extension

Record a separate conclusion for each scenario. A redirect to sign-in points the investigation toward permissions and the session. An HTML error in the body points toward the route, handler and relevant log. A correct document with an unsuitable name points toward header generation. A correct body with the wrong MIME type points toward response configuration. Do not apply a universal attachment header to every response: that may disguise error pages as files without fixing the underlying cause.

Before changing code or configuration, preserve its current version, reproduce the problem in a test environment and prepare to restore that version. Access changes must not make a private document public. Repeat a successful download, denial without permission and a missing-document case. Check the browser and an independent GET against the same expectations; HEAD can provide a useful preliminary view, but it does not check the received body.

In conclusion, the filename, status and response type must agree with the actual contents, and an interrupted download must be distinguished from an incorrect response. For redirect context, read checking redirects after a URL change (in Ukrainian). AriZone can help collect a safe diagnostic record and locate the cause without experimenting with private files. After the exercise, remove only the test copies you created; do not leave diagnostic headers in a public directory.