Replacing files in WordPress should be straightforward, but sometimes caching systems interfere and cause old versions of files to persist even after updates. Recently, our team resolved a case where replacing a PDF in the media library did not display the updated file on the frontend unless the filename was changed.
Issue Background
A client needed to replace product datasheets (PDFs) in their WordPress site. They used the “Replace Media” function to upload a new file with the same filename, expecting the change to apply across the site. However:
- The old PDF continued to display even after replacement.
- Changing the filename worked, but this was not sustainable for managing multiple product datasheets.
- The issue primarily affected PDFs, not images or other media.
Given that this site relied on accurate technical documents, ensuring the latest version displayed was critical.
Diagnosis
Our development team investigated the issue and identified the cause:
- The site was using WP Rocket caching along with Pressable’s server-level caching.
- Browser caching compounded the issue, meaning visitors’ browsers were serving old versions of the PDF.
- The “Replace Media” function technically uploaded the new file, but caching layers continued serving the older cached version.
Resolution Steps
To address this, our team implemented and tested several solutions:
- Staging tests
– Replicated the issue in a staging environment by replacing PDFs.
– Confirmed that caching was the root cause, as the old file persisted until a manual refresh or cache purge. - Cache purging attempts
– Added the PDF URLs to WP Rocket’s “Always Purge URL” list.
– Tested with server cache disabled.
– These methods did not consistently resolve the issue. - Versioning fix
– Implemented a script to automatically append a query string (e.g.,?v=timestamp) to PDF URLs when they were replaced.
– This forced browsers and caching layers to fetch the updated file instead of relying on the cached version. - Validation
– Replaced multiple PDFs and confirmed that the new versions displayed immediately without needing a filename change.
– Verified the fix on both frontend product pages and support resource pages.
Final Outcome
With the versioning solution in place, the site now reliably serves updated PDFs when replaced in the WordPress media library. Administrators no longer need to rename files to force updates, and users can be confident they are always accessing the latest datasheets.
This case highlights the importance of understanding caching behavior in WordPress and implementing smart workarounds like versioned query strings.
If your WordPress site is experiencing issues with media replacements, caching conflicts, or file versioning, Freshy can help implement solutions that ensure your files are always up to date. Contact Freshy today to get expert support for WordPress caching and file management.
