Error logs and debugging

Applies to

• WordPress 6.4–6.5, WooCommerce 8.x, PHP 7.4+
• Free and Pro editions

Plugin debug logging (recommended first)

The plugin can write its own debug and error messages to a log that you can view in the settings screen—no need to edit wp-config.php for plugin-specific issues.

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, then open the Free Download Error Logs section on the same Debug page to view the log in the browser.
4. The log file is also written to: wp-content/uploads/free-downloads-files/free_downloads_log.txt.
5. When you’re done troubleshooting, turn Enable Debug Logging off.

Use this for download, validation, and plugin logic issues. For general PHP or WordPress errors, use WordPress debug mode below.

Enabling debug mode

WordPress Debug Mode

Enable WordPress debugging to see detailed error messages.

Step 1: Edit wp-config.php

Add these lines before /* That's all, stop editing! */:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

Step 2: Check Debug Log

Errors are logged to: /wp-content/debug.log

Step 3: Disable When Done

Set back to false after debugging:

define('WP_DEBUG', false);

WooCommerce Logging

Enable WooCommerce logging for download-related errors.

Enable Logging:

1. Go to WooCommerce > Settings > Advanced > Logs
2. Enable logging
3. View logs in WooCommerce > Status > Logs

Common Error Messages

"File not found"

Error Message:

File not found: /path/to/file.pdf

Causes:

• File was deleted
• Incorrect file path
• File permissions issue
• File moved to different location

Solutions:

1. Verify file exists in correct location
2. Check file path in product settings
3. Verify file permissions (644 for files, 755 for directories)
4. Re-upload file if necessary

"Permission denied"

Error Message:

Permission denied: Cannot read file

Causes:

• Incorrect file permissions
• Server configuration issue
• PHP safe mode restrictions

Solutions:

# Fix file permissions
chmod 644 /path/to/file.pdf

# Fix directory permissions
chmod 755 /path/to/directory/

"Memory limit exceeded"

Error Message:

Fatal error: Allowed memory size exhausted

Causes:

• Large files being processed
• Many files in ZIP
• PDF watermarking large files
• Statistics export too large

Solutions:

Increase PHP Memory Limit:

In wp-config.php:

define('WP_MEMORY_LIMIT', '256M');
define('WP_MAX_MEMORY_LIMIT', '512M');

In .htaccess:

php_value memory_limit 256M

In php.ini:

memory_limit = 256M

"Maximum execution time exceeded"

Error Message:

Fatal error: Maximum execution time of 30 seconds exceeded

Causes:

• Large file downloads
• PDF watermarking
• Statistics export
• Slow server

Solutions:

Increase Execution Time:

In .htaccess:

php_value max_execution_time 300

In php.ini:

max_execution_time = 300

In code (temporary):

set_time_limit(300);

"ZIP creation failed"

Error Message:

Failed to create ZIP archive

Causes:

• ZipArchive extension not installed
• Insufficient disk space
• File permissions issue
• Temp directory not writable

Solutions:

1. Verify ZipArchive is installed:

<?php
if (class_exists('ZipArchive')) {
    echo 'ZipArchive is installed';
} else {
    echo 'ZipArchive is NOT installed';
}

2. Check disk space:

df -h

3. Verify temp directory permissions:

chmod 755 /wp-content/uploads/temp-files/

"Nonce verification failed"

Error Message:

Security check failed

Causes:

• Expired nonce (page open too long)
• Cache serving old nonce
• Session issues
• Time synchronization issue

Solutions:

1. Refresh page and try again
2. Clear all caches
3. Check server time is correct
4. Disable aggressive caching for download pages

"Download limit reached"

Error Message:

You have reached your download limit

Causes:

• User exceeded configured limit
• Limit configuration error
• Tracking not working correctly

Solutions:

1. Verify limit settings are correct
2. Check tracking is enabled
3. Review user's download history
4. Adjust limits if needed
5. Clear limit for specific user if appropriate

"Email capture validation failed"

Error Message:

Please enter a valid email address

Causes:

• Invalid email format
• Required fields empty
• JavaScript validation error
• Spam prevention triggered

Solutions:

1. Verify email format is correct
2. Fill all required fields
3. Wait 2+ seconds before submitting
4. Clear browser cache
5. Disable browser extensions

"MailChimp API error"

Error Message:

MailChimp subscription failed: [error details]

Common Errors:

Invalid API Key:

API Key Invalid

Solution: Verify API key in settings

List Not Found:

Resource Not Found

Solution: Verify list ID is correct

Already Subscribed:

Member Exists

Solution: This is normal, user already subscribed

Rate Limit:

Too Many Requests

Solution: Wait and try again, reduce subscription frequency

Debugging Tools

Browser Developer Tools

Open Console:

• Chrome/Edge: F12 or Ctrl+Shift+J
• Firefox: F12 or Ctrl+Shift+K
• Safari: Cmd+Option+C

Check for JavaScript Errors:

1. Open console
2. Reload page
3. Look for red error messages
4. Note file and line number

Monitor Network Requests:

1. Open Network tab
2. Click download button
3. Check for failed requests
4. View request/response details

WordPress Plugins

Query Monitor

Install and activate Query Monitor plugin.

Features:

• Database queries
• PHP errors
• Hooks and actions
• HTTP requests
• Environment info

Debug Bar

Install and activate Debug Bar plugin.

Features:

• PHP notices and warnings
• SQL queries
• WP_Query details
• Object cache stats

Server Logs

Apache Error Log:

tail -f /var/log/apache2/error.log

Nginx Error Log:

tail -f /var/log/nginx/error.log

PHP Error Log:

tail -f /var/log/php/error.log

Debugging Specific Issues

Downloads Not Working

Step 1: Check Product Configuration

// Add to functions.php temporarily
add_action('wp_footer', 'debug_product_config');
function debug_product_config() {
    if (is_product()) {
        global $product;
        echo '<pre>';
        echo 'Product ID: ' . $product->get_id() . "\n";
        echo 'Is Downloadable: ' . ($product->is_downloadable() ? 'Yes' : 'No') . "\n";
        echo 'Is Virtual: ' . ($product->is_virtual() ? 'Yes' : 'No') . "\n";
        echo 'Price: ' . $product->get_price() . "\n";
        echo 'Files: ' . print_r($product->get_downloads(), true);
        echo '</pre>';
    }
}

Step 2: Check Plugin Settings

// Check if product is valid for free download
$is_valid = somdn_is_product_valid($product_id);
var_dump($is_valid);

Step 3: Check File Paths

// Verify file exists
$files = somdn_get_files($product_id);
foreach ($files as $file) {
    $path = $file['file'];
    echo $path . ': ' . (file_exists($path) ? 'EXISTS' : 'NOT FOUND') . "\n";
}

Email Capture Not Showing

Debug Script:

// Add to browser console
console.log('Email capture active:', somdn_script_params.capture_email_active);
console.log('Capture users:', somdn_script_params.capture_users);
console.log('User logged in:', document.body.classList.contains('logged-in'));
console.log('Capture function exists:', typeof somdn_open_email_capture);

Limits Not Enforcing

Debug Limits:

// Add to functions.php temporarily
add_action('wp_footer', 'debug_limits');
function debug_limits() {
    if (is_user_logged_in()) {
        $user_id = get_current_user_id();
        $limits = somdn_get_user_limits($user_id, 0);
        echo '<pre>';
        print_r($limits);
        echo '</pre>';
        
        $reached = somdn_has_user_reached_limit($user_id, 0, 0);
        echo 'Limit reached: ' . ($reached ? 'Yes' : 'No');
    }
}

Statistics Not Recording

Check Tracking:

// Verify tracking is enabled
$tracking_settings = get_option('somdn_pro_track_settings');
var_dump($tracking_settings);

// Check recent downloads
$downloads = get_posts(array(
    'post_type' => 'somdn_tracked',
    'posts_per_page' => 10,
    'orderby' => 'date',
    'order' => 'DESC'
));
var_dump($downloads);

Performance Debugging

Slow Downloads

Check Server Resources:

# CPU usage
top

# Memory usage
free -m

# Disk I/O
iostat

Profile PHP:

// Add timing
$start = microtime(true);
somdn_download_single();
$end = microtime(true);
error_log('Download time: ' . ($end - $start) . ' seconds');

Database Performance

Slow Queries:

Enable slow query log in MySQL:

SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

Optimize Tables:

OPTIMIZE TABLE wp_posts;
OPTIMIZE TABLE wp_postmeta;

Add Indexes:

-- Index for download logs
ALTER TABLE wp_postmeta ADD INDEX somdn_product_id (meta_key, meta_value);

Error Log Analysis

Reading Debug Log

Log Format:

[10-Nov-2024 10:30:45 UTC] PHP Warning: [error message] in [file] on line [number]

Common Patterns:

Undefined Variable:

PHP Notice: Undefined variable: variable_name

Solution: Initialize variable before use

Undefined Index:

PHP Notice: Undefined index: array_key

Solution: Check if key exists before accessing

Function Not Found:

PHP Fatal error: Call to undefined function function_name()

Solution: Check plugin is activated, function exists

Class Not Found:

PHP Fatal error: Class 'ClassName' not found

Solution: Check autoloading, include file

Filtering Logs

Find Plugin Errors:

grep "somdn" /wp-content/debug.log

Find Fatal Errors:

grep "Fatal error" /wp-content/debug.log

Find Recent Errors:

tail -100 /wp-content/debug.log

Count Error Types:

grep -c "Warning" /wp-content/debug.log
grep -c "Fatal" /wp-content/debug.log

Best Practices

Development Environment

• Always use staging site for debugging
• Enable all error reporting
• Use version control
• Keep backups
• Document changes

Production Environment

• Disable debug display
• Enable debug logging
• Monitor error logs regularly
• Set up error notifications
• Keep logs secure

Code Debugging

• Use descriptive variable names
• Add comments for complex logic
• Use error_log() for debugging
• Remove debug code before deployment
• Test thoroughly

Collect for support

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

• Error messages: Exact error text, full excerpt from debug.log, and any browser console errors
• Environment: WordPress version, WooCommerce version, plugin version (Basic/Pro), PHP version, server type
• Steps to reproduce: What you did, what you expected, what actually happened
• Configuration: Relevant plugin settings and product configuration
• Logs: Relevant debug.log entries, server error log path, and browser console output

What's Next

• Troubleshooting - Common issues and fixes
• Migration guide - Upgrade and migration issues
• Support and resources - Where to get help