Skip to main content

Troubleshooting

Symptom​

You are experiencing issues with Free Downloads for WooCommerce: the download button is not showing on product pages, clicking download does not work, ZIP files are not creating, styling does not match your theme, or you see login, membership, or performance problems.

Applies To​

  • WordPress 6.4 – 6.5
  • WooCommerce 8.0 – 8.5
  • Free Downloads for WooCommerce (free and Pro editions)

Likely Causes​

  1. Product not set up correctly – Price not exactly zero, product not downloadable/virtual, or no files attached
  2. File or URL issues – Invalid file URLs, external files used for ZIP, or permission problems
  3. Cache – Browser, server, or plugin cache showing old content
  4. Plugin or theme conflict – Another plugin or theme interfering with downloads or display
  5. Server configuration – PHP memory, execution time, or ZipArchive not available

Fix​

Work through the sections below that match your issue. Start with the most common: download button not showing.

Download Button Not Showing​

The most common issue is the download button not appearing on product pages.

Checklist​

Work through these checks in order:

  1. ✅ Product Price

    • Price must be exactly 0 (zero)
    • Not 0.01, not empty, exactly 0
    • Check both regular price and sale price

  2. ✅ Product Type

    • Downloadable checkbox must be checked
    • Virtual checkbox must be checked
    • Both are required

  3. ✅ Downloadable Files

    • At least one file must be added
    • File URL must be valid
    • File must be accessible

  4. ✅ Product Selection Settings

    • If "Include selected products only" is enabled
    • Check "Include this product" on product edit page

  5. ✅ Cache

    • Clear browser cache
    • Clear server cache
    • Clear any caching plugins
    • Test in incognito/private mode

  6. ✅ Plugin Active

    • Verify plugin is activated
    • Check for plugin conflicts
    • Try disabling other plugins temporarily

  7. ✅ Page builders (Elementor, Divi, etc.)

    • If you build product pages with a page builder, their product blocks or modules often do not include the WooCommerce hooks where the plugin injects the download button.
    • Solution: Use the [download_now] shortcode instead. Add a Shortcode (or Code/HTML) block or widget and insert [download_now id="123"] with your product ID. The shortcode works regardless of hooks. See Shortcodes reference.

Still Not Working?​

If the button still doesn't show:

functions.php
// Add this to your theme's functions.php temporarily for debugging
add_action('wp_footer', function() {
    if (is_product()) {
        global $product;
        echo '<!-- Debug: Product ID: ' . $product->get_id() . ' -->';
        echo '<!-- Debug: Price: ' . $product->get_price() . ' -->';
        echo '<!-- Debug: Downloadable: ' . ($product->is_downloadable() ? 'Yes' : 'No') . ' -->';
        echo '<!-- Debug: Virtual: ' . ($product->is_virtual() ? 'Yes' : 'No') . ' -->';
    }
});

View page source and check the HTML comments for debug info.

Download Not Working​

Button appears but clicking doesn't download the file.

Common Causes​

File URL Issues​

Problem: File URL is incorrect or inaccessible

Solution:

  1. Edit the product
  2. Check the file URL in downloadable files
  3. Click the URL to test it directly
  4. Ensure file exists on server
  5. Check file permissions (should be readable)

JavaScript Errors​

Problem: JavaScript conflicts preventing download

Solution:

  1. Open browser console (F12)
  2. Look for JavaScript errors
  3. If errors present, disable plugins one by one
  4. Test with default WordPress theme

Nonce Expired​

Problem: Security nonce has expired (after 24 hours)

Solution:

  1. Refresh the page
  2. Try download again
  3. Nonces regenerate on page load

Server Issues​

Problem: Server configuration blocking downloads

Solution:

  1. Check server error logs
  2. Verify PHP memory limit (128MB minimum)
  3. Check max execution time (30 seconds minimum)
  4. Contact hosting support if needed

ZIP Files Not Creating​

Multiple file products not creating ZIP files.

External File URLs​

Problem: Files are external URLs, not uploaded to WordPress

Solution:

  • ZIP creation only works with files hosted on your server
  • Use "Links Only" display method for external files
  • Or upload files to WordPress using "Choose File" option

PHP ZipArchive Not Available​

Problem: Server doesn't have ZipArchive extension

Solution:

  1. Check if ZipArchive is available:
check-ziparchive.php
<?php
if (class_exists('ZipArchive')) {
    echo 'ZipArchive is available';
} else {
    echo 'ZipArchive is NOT available';
}
?>
  1. If not available, contact hosting support to enable it
  2. Or use "Links Only" display method

File Permissions​

Problem: Plugin can't write to uploads directory

Solution:

  1. Check /wp-content/uploads/ is writable
  2. Check /wp-content/uploads/somdn-zips/ exists and is writable
  3. Set permissions to 755 or 775
  4. Contact hosting support if needed

Memory Limit​

Problem: Not enough memory to create large ZIPs

Solution:

  1. Increase PHP memory limit in wp-config.php:
wp-config.php
define('WP_MEMORY_LIMIT', '256M');
  1. Or reduce file sizes
  2. Or use "Links Only" for large files

Styling Issues​

Download buttons don't match your theme.

Button Classes Not Applied​

Problem: Custom button classes not working

Solution:

  1. Go to WP Enhanced > Free Download Woo, click General in the sidebar, then set Button classes
  2. Add your theme's button classes
  3. Common classes: btn, btn-primary, button, wp-block-button__link
  4. Clear cache and test

CSS Not Applied​

Problem: Custom CSS not taking effect

Solution:

  1. Check CSS specificity using browser inspector
  2. Your CSS may need !important
  3. Ensure CSS is loaded after plugin CSS
  4. Clear browser cache

Button Too Small/Large​

Problem: Button size doesn't match theme

Solution: Add padding in Button CSS setting:

padding: 12px 24px;
font-size: 16px;

Wrong Colors​

Problem: Button colors don't match theme

Solution: Add colors in Button CSS setting:

background-color: #0073aa;
color: white;
border: none;

Login Issues​

Problems with login requirements.

Login Required But Button Shows​

Problem: "Require login" is enabled but guests see button

Solution:

  1. Clear all caches
  2. Test in incognito mode
  3. Check setting is actually saved
  4. Verify you're logged out when testing

Logged In But Can't Download​

Problem: User is logged in but still sees login message

Solution:

  1. Clear browser cookies
  2. Log out and log back in
  3. Check user has proper role/capabilities
  4. Clear all caches

Redirect After Login Not Working​

Problem: After login, user not redirected back to product

Solution:

  1. Check for custom login page plugins
  2. Verify no redirect filters interfering
  3. Test with default WordPress login
  4. Disable other plugins temporarily

WooCommerce Memberships Issues​

Problems with membership restrictions.

Members Can't Download​

Problem: Members see membership message instead of button

Solution:

  1. Verify membership is active (not expired)
  2. Check product is restricted to correct plan
  3. Ensure user is logged in
  4. Check membership plan includes product access
  5. Clear all caches

Non-Members See Button​

Problem: Non-members see download button

Solution:

  1. Verify product restriction is saved
  2. Check membership plan is active
  3. Ensure WooCommerce Memberships is active
  4. Clear caches
  5. Test in incognito mode

PDF Viewer Issues​

PDF viewer not working.

"View PDF" Button Not Showing​

Problem: Button doesn't appear for PDFs

Solution:

  1. Verify PDF Viewer is enabled in settings
  2. Check file is actually a PDF (.pdf extension)
  3. Ensure file is attached to product
  4. Clear caches

PDF Doesn't Load​

Problem: Clicking "View PDF" doesn't work

Solution:

  1. Verify PDF URL is publicly accessible
  2. Check file size (should be under 10MB)
  3. Test PDF URL directly in browser
  4. Ensure no authentication required
  5. Check if file is corrupted

PDF Displays Incorrectly​

Problem: PDF renders wrong in viewer

Solution:

  1. Check original PDF file
  2. Verify PDF isn't corrupted
  3. Try different PDF viewer
  4. Consider PDF complexity (some features may not render)
  5. Reduce file size if too large

Shop Page Issues​

Problems with downloads on shop/archive pages.

Download Button Not on Shop Page​

Problem: Button doesn't appear on shop pages

Solution:

  1. Enable "Allow download on shop / archive pages" in settings
  2. Verify product has only one file (multiple files always show "Read More")
  3. Clear caches
  4. Check theme compatibility

"Read More" Shows Instead of Download​

Problem: Shows "Read More" when should show download

Solution:

  • This is normal for multiple-file products
  • Only single-file products show download on shop pages
  • Or "Allow download on shop / archive pages" is disabled

Theme Conflicts​

Plugin not working with your theme.

Common Theme Issues​

Divi Theme:

  • May need to adjust button classes
  • Check for custom add-to-cart scripts
  • Test with Divi's default product layout

Flatsome Theme:

  • May conflict with Quick View
  • Check Flatsome's product page customizations
  • Test with default Flatsome product layout

Astra Theme:

  • Usually works well
  • Check Astra's WooCommerce settings
  • Verify no custom product page layouts

OceanWP Theme:

  • Generally compatible
  • Check OceanWP's WooCommerce options
  • Test with default product layout

General Theme Troubleshooting​

  1. Test with default WordPress theme (Twenty Twenty-Four)
  2. If works with default theme, it's a theme conflict
  3. Contact theme support
  4. Or use template overrides to fix

Plugin Conflicts​

Another plugin interfering.

Common Conflicts​

WooCommerce Product Add-ons:

  • May interfere with button display
  • Check add-ons aren't required for free products

WooCommerce Subscriptions:

  • Usually compatible
  • Check subscription settings

Caching Plugins:

  • Clear cache after any changes
  • Exclude product pages from cache if needed

Security Plugins:

  • May block downloads
  • Check security plugin logs
  • Whitelist plugin if needed

Finding Conflicts​

  1. Deactivate all other plugins
  2. Test if download works
  3. Reactivate plugins one by one
  4. Test after each activation
  5. When it breaks, you found the conflict

Performance Issues​

Downloads are slow or timing out.

Large Files​

Problem: Large files timeout during download

Solution:

  1. Increase PHP max_execution_time:
wp-config.php
@ini_set('max_execution_time', 300);
  1. Or use CDN for large files
  2. Or compress files before uploading

Large ZIPs​

Problem: Creating ZIP times out

Solution:

  1. Increase PHP memory limit
  2. Increase max_execution_time
  3. Reduce number of files per product
  4. Use "Links Only" for large file collections

Server Resources​

Problem: Server runs out of resources

Solution:

  1. Upgrade hosting plan
  2. Optimize file sizes
  3. Use CDN for file delivery
  4. Limit concurrent downloads

Database Issues​

Problems with download tracking or limits.

Download Count Not Increasing​

Problem: Download count stays at 0

Solution:

  1. Check if tracking is enabled (Pro feature)
  2. Verify downloads are actually happening
  3. Check database for somdn_dlcount meta
  4. Clear object cache if using one

Old Download Records​

Problem: Too many download records in database

Solution:

  1. Old records are automatically cleaned up
  2. ZIP files deleted after 1 hour
  3. Check cron is running properly
  4. Manually clean if needed

Verify​

After applying a fix, reload the product page (use incognito or a cleared cache), confirm the download button appears or the download completes as expected, and test with a different browser if needed.

Collect for Support​

If the fix does not work, collect this information before contacting support:

  • WordPress version
  • WooCommerce version
  • Free Downloads for WooCommerce version (free or Pro)
  • PHP version
  • Theme name and version
  • List of active plugins
  • Error messages (exact text)
  • Screenshots of the issue
  • Steps to reproduce
  • Plugin debug log output (see below)

Use the plugin’s debug logging​

The plugin has a dedicated Debug section that writes errors and debug messages to a log you can view in settings.

  1. Go to WP Enhanced > Free Download Woo, then click Debug in the sidebar.
  2. Turn on Enable Debug Logging and save.
  3. Reproduce the issue (e.g. try the download again).
  4. On the same Debug page, open the Free Download Error Logs section to view the log in the browser, or check the log file at wp-content/uploads/free-downloads-files/free_downloads_log.txt.
  5. Copy the relevant log lines (or attach the file) when contacting support.
  6. When you’re done, turn Enable Debug Logging off.

For general PHP/WordPress errors you can also enable WordPress debug and check wp-content/debug.log. See Error logs and debugging for details.

Where to get help​

Free Edition:
Visit the WordPress.org support forum for Free Downloads for WooCommerce. The WP Enhanced team monitors the forum; you can also search existing topics and get help from the community. Include WordPress version, PHP version, and plugin version when posting.

Pro Edition:
Submit support tickets through the WP Enhanced website. Premium support is included with your license. Include your license key when contacting support.

What's Next​