Common Issues

Updated Jan 26, 2026 Troubleshooting

Overview

This guide covers the most frequently encountered issues with WordPress Download Manager and their solutions. If you don’t find your issue here, check the Error Messages guide or contact support.

Download Issues

Downloads Not Starting

Symptoms:

Clicking download button does nothing
Page refreshes without download
Browser shows “waiting” indefinitely

Causes & Solutions:

JavaScript Conflict

   Check: Open browser console (F12) → Console tab
   Look for: Red error messages

Solution: Deactivate other plugins one by one to find conflict. Common culprits:
– Caching plugins (disable for logged-in users)
– Minification plugins
– Security plugins blocking scripts

Incorrect Permalink Settings

   Go to: Settings → Permalinks
   Action: Click "Save Changes" (without changing anything)

This flushes rewrite rules and often fixes download links.

File Path Issues

   Check: Downloads → All Packages → Edit package
   Verify: Files are properly attached and paths are correct

Download Starts But File is Corrupted

Symptoms:

ZIP files won’t open
PDF shows blank
File size is wrong

Causes & Solutions:

PHP Output Before Download

   // Check for whitespace before <?php in theme files
   // Check for BOM (Byte Order Mark) in PHP files

Solution: Remove any whitespace or output before download headers.

Memory Limit Too Low

   // Add to wp-config.php
   define('WP_MEMORY_LIMIT', '256M');

Timeout for Large Files

   // Add to wp-config.php or .htaccess
   set_time_limit(300);

“File Not Found” Error

Causes & Solutions:

File Moved or Deleted

– Check upload directory: wp-content/uploads/download-manager-files/
– Re-upload file if missing

Permission Issues

   # Set correct permissions
   chmod 755 wp-content/uploads/download-manager-files/
   chmod 644 wp-content/uploads/download-manager-files/*

Symbolic Link Issues

– If using symlinks, ensure target exists
– Check symlink permissions

Access Control Issues

Users Can’t Access Downloads

Symptoms:

“Permission Denied” message
Download button not showing
Redirect to login

Causes & Solutions:

Role Configuration

   Check: Package → Access tab
   Verify: User's role is in allowed list

Guest Access Disabled

   Check: Package → Access tab
   Enable: "Guest" in allowed roles for public downloads

Category-Level Restrictions

   Check: Downloads → Categories → Edit category
   Verify: Category access settings

Download Limit Reached Incorrectly

Symptoms:

User blocked but hasn’t reached limit
Limit resets unexpectedly

Causes & Solutions:

Multiple User Sessions

– Same user logged in from multiple devices counts separately
– Solution: Clear user’s download count in database

Caching Issues

   Check: Caching plugin settings
   Exclude: /download/* URLs from cache

Reset Download Count

   -- In phpMyAdmin or database tool
   DELETE FROM wp_ahm_user_download_counts
   WHERE user = [user_id] AND package_id = [package_id];

Lock Issues

Password Lock Not Working

Symptoms:

Correct password rejected
Lock doesn’t appear
Can download without password

Causes & Solutions:

JavaScript Not Loading

– Check browser console for errors
– Ensure jQuery is loaded

Password Contains Special Characters

– Try simpler password without special characters
– Check encoding issues

Caching Bypass

   Exclude from cache:
   - Pages with [wpdm_package] shortcode
   - AJAX endpoints

Email Lock Emails Not Sending

Symptoms:

User submits email but no confirmation
Emails go to spam
No email received

Causes & Solutions:

WordPress Email Not Configured

   Solution: Install SMTP plugin (WP Mail SMTP, FluentSMTP)
   Test: Tools → Site Health → Info → Email

Email Blocked by Domain

   Check: Downloads → Settings → Email Lock
   Review: Blocked domains list

SPF/DKIM Not Set

– Configure proper email authentication
– Use transactional email service

CAPTCHA Not Displaying

Causes & Solutions:

API Keys Missing

   Check: Downloads → Settings → Locks → reCAPTCHA
   Verify: Site key and Secret key are correct

Domain Mismatch

– reCAPTCHA keys are domain-specific
– Add all domains (with/without www)

JavaScript Blocked

– Check if security plugin blocks Google scripts
– Whitelist recaptcha.net

Template Issues

Template Not Displaying Correctly

Symptoms:

Wrong template used
Missing elements
Broken layout

Causes & Solutions:

Template Override Conflict

   Check: Theme folder for template overrides
   Path: your-theme/download-manager/templates/

Cache Showing Old Template

   Clear:
   - Browser cache
   - WordPress cache
   - CDN cache

Template Not Selected

   Check: Package → Template tab
   Or: Downloads → Settings → Templates

Custom Template Tags Not Working

Causes & Solutions:

Incorrect Tag Syntax

   Correct: [download_link]
   Wrong: {download_link} or {{download_link}}

Tag Not Available for Template Type

– Some tags only work in page templates
– Check template tag documentation

Premium Package Issues

Payment Not Processing

Symptoms:

Stuck on checkout
Payment fails
Order stays pending

Causes & Solutions:

SSL Certificate Issues

   Verify: Site uses HTTPS
   Check: SSL certificate is valid

Gateway Credentials Wrong

   Stripe: Check API keys (live vs test)
   PayPal: Verify email and API credentials

Currency Not Supported

– Verify currency is supported by gateway
– Check gateway account settings

License Keys Not Generating

Causes & Solutions:

License Settings Not Enabled

   Check: Package → Pricing → Enable License

License Format Issue

   Check: Downloads → Settings → Licenses → Key Format

Order Emails Not Sending

Causes & Solutions:

Email Templates Disabled

   Check: Downloads → Settings → Emails
   Enable: Relevant email notifications

SMTP Issues

– Same solutions as Email Lock emails

Performance Issues

Slow Package Listing

Causes & Solutions:

Too Many Packages Loading

   Solution: Use pagination
   [wpdm_packages items_per_page="20"]

Complex Queries

   Check: Multiple category/tag filters
   Solution: Simplify shortcode parameters

Database Optimization Needed

   -- Optimize WPDM tables
   OPTIMIZE TABLE wp_ahm_download_stats;
   OPTIMIZE TABLE wp_postmeta;

Admin Panel Slow

Causes & Solutions:

Large Statistics Table

   Check: Downloads → Statistics → Archive old data
   Solution: Archive or delete old stats

Too Many Packages

– Use search/filter instead of browsing
– Increase PHP memory limit

Cloud Storage Issues

S3 Files Not Downloading

Causes & Solutions:

Credentials Expired

– Regenerate IAM access keys
– Update in WPDM settings

Bucket Policy

   {
     "Version": "2012-10-17",
     "Statement": [{
       "Effect": "Allow",
       "Principal": "*",
       "Action": "s3:GetObject",
       "Resource": "arn:aws:s3:::bucket-name/*"
     }]
   }

Region Mismatch

– Verify bucket region in settings
– Check endpoint URL

Google Drive Authorization Failed

Causes & Solutions:

Token Expired

   Solution: Re-authorize connection
   Downloads → Settings → Google Drive → Reconnect

API Quota Exceeded

– Wait for quota reset
– Request quota increase from Google

Quick Fixes Checklist

When troubleshooting, try these first:

Clear All Caches

– Browser cache
– WordPress cache plugin
– CDN cache
– Server cache (OPcache)

Flush Permalinks

– Settings → Permalinks → Save Changes

Deactivate/Reactivate WPDM

– Sometimes resets stuck states

Check PHP Error Log

   Location: /wp-content/debug.log
   Enable: define('WP_DEBUG_LOG', true);

Test with Default Theme

– Switch to Twenty Twenty-Four
– If works, theme conflict exists

Increase Memory/Timeout

   // wp-config.php
   define('WP_MEMORY_LIMIT', '256M');
   define('WP_MAX_MEMORY_LIMIT', '512M');
   set_time_limit(300);

Getting Help

If issues persist:

Check Documentation

– Search docs for specific error
– Review related feature guides

Community Forum

– Search existing topics
– Post with details and screenshots

Support Ticket

– Include WordPress version
– Include WPDM version
– Include PHP version
– Include error messages
– Include steps to reproduce

Overview

Download Issues

Downloads Not Starting

Download Starts But File is Corrupted

“File Not Found” Error

Access Control Issues

Users Can’t Access Downloads

Download Limit Reached Incorrectly

Lock Issues

Password Lock Not Working

Email Lock Emails Not Sending

CAPTCHA Not Displaying

Template Issues

Template Not Displaying Correctly

Custom Template Tags Not Working

Premium Package Issues

Payment Not Processing

License Keys Not Generating

Order Emails Not Sending

Performance Issues

Slow Package Listing

Admin Panel Slow

Cloud Storage Issues

S3 Files Not Downloading

Google Drive Authorization Failed

Quick Fixes Checklist

Getting Help

Related Documentation