DEV Community

Cover image for Why DigitalOcean Spaces Auto-Downloads Large PDFs - And How to Fix It
Tahsin Abrar
Tahsin Abrar

Posted on

Why DigitalOcean Spaces Auto-Downloads Large PDFs - And How to Fix It

#digitalocean #pdf #webdev #httpheaders

If you're using DigitalOcean Spaces to serve static files like images, PDFs, or videos, you may have noticed something odd:
When you try to open a large PDF file (say 20MB+) using a direct URL, instead of showing a preview in the browser, it just downloads automatically.

Frustrating, right? Especially when you're expecting your users to view the file directly in their browser.

Today, we’ll explore:

  • Why this happens
  • How headers like Content-Disposition affect behavior
  • And most importantly: How to fix it — step by step

🧐 The Problem: Browser Doesn't Preview Large PDF Files from DigitalOcean

Let’s say your file lives at:

https://your-space-name.sgp1.cdn.digitaloceanspaces.com/sample.pdf
Enter fullscreen mode Exit fullscreen mode

If the file is small (like under 5MB), the browser might preview it normally.
But if it's a larger PDF (10MB, 20MB, or more), clicking that URL will force a download instead of previewing it.

Why? Two key reasons.

🔍 Root Cause #1: The Content-Disposition Header

When a file is served over HTTP, the server includes headers that tell the browser how to handle it. One important header is:

Content-Disposition: attachment
Enter fullscreen mode Exit fullscreen mode

That attachment part tells the browser:

“Hey, don’t try to preview this — just download it.”

If you want the file to open in-browser, the header must be:

Content-Disposition: inline
Enter fullscreen mode Exit fullscreen mode

So, if your uploaded file has attachment, no matter the file type, it will be downloaded.

🔍 Root Cause #2: CDN Behavior for Large Files

DigitalOcean Spaces sits on top of a CDN (Content Delivery Network).
For large files (like 10MB+), the CDN might default to a download mode to reduce bandwidth strain and caching complexity.

It’s not officially documented, but many developers have reported the same — especially when uploading via third-party tools without specifying headers.

✅ The Fix: Set Headers Correctly When Uploading

To ensure PDF preview works as expected:

✅ Step 1: Set Content-Type and Content-Disposition

If you're using the AWS CLI (which also works with DigitalOcean Spaces), here’s how to upload:

aws s3 cp ./sample.pdf s3://your-space-name/ \
  --endpoint-url https://sgp1.digitaloceanspaces.com \
  --content-type application/pdf \
  --content-disposition inline
Enter fullscreen mode Exit fullscreen mode

This ensures:

  • Your file is marked as a PDF
  • The browser knows it can preview it (inline)

⚠️ If you've already uploaded the file, you’ll need to re-upload or use the SDK to update the metadata.

✅ Step 2: Verify the Headers

After uploading, open DevTools → Network tab and click your file URL. Check the response headers:

  • ✅ Content-Type: application/pdf
  • ✅ Content-Disposition: inline

If those are in place, your browser should now preview the file, no matter its size.

Top comments (0)