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

Most FileDeck download problems come from one of three places: permalink rules that need refreshing, 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 the plugin endpoint (/fdk-download/{id}, or the REST equivalent /wp-json/fdk/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: WordPress has not registered the rewrite rule for the pretty download URL /fdk-download/{id}. This typically happens right after installing or updating a plugin, migrating a site, or when your permalink settings interfere.

Fix:

1. Go to Settings → Permalinks in wp-admin.
2. Click Save Changes without changing anything. This flushes and rebuilds the rewrite rules.
3. Reload the library page and test a download link again.

One important exception: the Plain permalink structure (?p=123) does not support pretty URLs, so /fdk-download/{id} links cannot work with it. Either switch to any other permalink structure under Settings → Permalinks, or rely on the REST route /wp-json/fdk/v1/download/{id}, which works regardless of your permalink setting.

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 /fdk-download/ (and /wp-json/fdk/v1/download/ if you cache REST responses). 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?

The rewrite rule for /fdk-download/ needs refreshing. Go to Settings → Permalinks and click Save Changes to flush the rules.

Do I need to exclude anything from my caching plugin?

Yes — exclude the /fdk-download/ path 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.