Downloads not working: 404s, wrong file, or zero counts Free & Pro

Most FileDeck download problems come from one of three places: something blocking the WordPress REST API, a caching layer sitting between the visitor and the download endpoint, or a missing PHP extension on the server. Every download in FileDeck routes through one REST endpoint — /wp-json/filedeck/v1/download/{id} — so that endpoint is where to look first. Find your symptom below and apply the fix.

Download links return a 404

Cause: The REST API isn’t reachable. FileDeck’s download endpoint lives on the WordPress REST API, so anything that blocks or rewrites /wp-json/ breaks every download link. The usual culprits are a security plugin that disables the REST API for logged-out visitors, a firewall or host rule blocking /wp-json/, or a server rewrite that never passes /wp-json/ to WordPress.

Fix:

1. Open https://your-site.com/wp-json/filedeck/v1/download/123 (any real document ID) in a private browsing window. A working setup returns the file or a redirect to it; a 404 page means the REST route isn’t being reached.
2. If it 404s, temporarily disable security plugins one at a time and retest — look for anything offering to "disable the REST API" or restrict it to logged-in users.
3. Ask your host whether a firewall rule blocks /wp-json/.
4. Go to Settings → Permalinks and click Save Changes once. This won’t fix a blocked REST API, but it does clear up rewrite oddities left by a migration.

Note that the Plain permalink structure is fine: WordPress serves the same route as ?rest_route=/filedeck/v1/download/{id}, and FileDeck generates whichever form your site is using. You do not need pretty permalinks for downloads to work.

The download serves an old file after a replacement

Cause: You replaced a document’s file, but visitors still receive the previous version. A page cache or CDN is serving a cached copy of the old redirect or the old file, or the visitor’s browser has cached it. With version history in Pro, the document’s URL never changes between versions, which is exactly why a caching layer can keep handing out the stale copy.

Fix:

1. Purge your page cache (caching plugin or host-level cache).
2. Purge your CDN cache if one sits in front of the site.
3. Ask the visitor to hard-refresh, or test in a private browsing window to rule out browser cache.

Download counts stay at zero or stop incrementing

Cause: A page cache is caching the download endpoint’s redirect response. When the cached redirect is served, the visitor still gets the file, but FileDeck’s code never runs, so the counter never increments.

Fix: Exclude the download endpoint from page caching. In your caching plugin’s exclusion settings, add the path /wp-json/filedeck/v1/download/ (and rest_route=/filedeck/v1/download if your site uses Plain permalinks). Do the same in any CDN page rules. Counts resume incrementing immediately; downloads served from cache before the exclusion are not recovered. See download counts for how counting works.

A permitted user is denied a protected download

Cause: With Pro access control, a protected download is refused when the visitor does not currently satisfy the restriction — even if you believe they should. The two most common reasons:

• They are logged out. Login sessions expire; the user may look logged in from an old tab but no longer has a valid session.
• Role mismatch. One of the document’s categories is restricted to a role the user does not actually have. Role restrictions are set per category, so a document inherits them from every category it belongs to.

Fix:

1. Ask the user to log out and log back in, then retry.
2. Check the user’s role under Users in wp-admin against the roles ticked on the restricted category.
3. Review the Restrict to roles (FileDeck) settings on all of the document’s categories under Documents → Document Categories.

Also note that protected downloads use signed URLs that expire after 15 minutes, so a copied or bookmarked download link stops working by design. See file protection and signed URLs.

Zip downloads fail

Cause: Multi-select zip downloads (Pro) require the PHP ZipArchive extension. If it is missing, FileDeck cannot build the archive.

Fix: Ask your host to enable the ZipArchive PHP extension. It is present on nearly all hosts, and enabling it is usually a quick support request. Single-file downloads are unaffected either way.

FAQ

Why do my FileDeck download links 404 after an update or migration?

Almost always because the WordPress REST API isn’t reachable. FileDeck downloads run through /wp-json/filedeck/v1/download/{id}, so a security plugin, firewall rule or server config that blocks /wp-json/ breaks every download link. Open that URL directly in a private window to confirm, then check your security plugin and ask your host about firewall rules.

Do I need to exclude anything from my caching plugin?

Yes — exclude /wp-json/filedeck/v1/download/ from page caching. Otherwise cached redirects can serve stale files and prevent download counts from incrementing.

Why does a shared download link stop working after a while?

For protected documents, download links are signed and expire after 15 minutes. Visitors should use the download button in the library rather than a saved link.