Something is broken on your WordPress site. Maybe a plugin is throwing errors, a page isn’t loading correctly, or the admin dashboard is sluggish for no obvious reason. You could spend hours guessing, or you could check the debug log — WordPress’s built-in tool for recording exactly what’s going wrong under the hood.

The WordPress debug log is one of the most useful troubleshooting tools available, but most site owners either don’t know it exists or aren’t sure how to use it. This guide covers everything: how to enable it, how to read it, and how to use the information to actually fix problems.

What Is the WordPress Debug Log?

WordPress is built on PHP, and like all PHP applications, it generates errors, warnings, and notices when something doesn’t work as expected. By default, WordPress suppresses these messages so they don’t appear on your live site (which is good — visitors shouldn’t see PHP errors). But that means the errors still happen silently, causing problems you can’t see.

The debug log is a text file where WordPress records these errors instead of displaying them. When enabled, every PHP error, warning, deprecated function notice, and database error gets written to a file called debug.log in your wp-content directory. It’s essentially a black box recorder for your website.

How to Enable WordPress Debug Mode

Debug mode is controlled by constants in your wp-config.php file, which sits in the root directory of your WordPress installation. You’ll need FTP access or a file manager in your hosting control panel to edit it.

Add or modify these lines in wp-config.php, placed before the line that says “That’s all, stop editing!”:

// Enable WordPress debug mode
define( 'WP_DEBUG', true );

// Log errors to wp-content/debug.log instead of displaying them
define( 'WP_DEBUG_LOG', true );

// Don't display errors on the live site
define( 'WP_DEBUG_DISPLAY', false );

// Log all PHP errors
@ini_set( 'display_errors', 0 );

Here’s what each constant does:

  • WP_DEBUG: The master switch. Set to true to enable debug mode.
  • WP_DEBUG_LOG: When true, errors are written to wp-content/debug.log.
  • WP_DEBUG_DISPLAY: When false, errors are hidden from visitors. Always set this to false on live sites.

Important: Never set WP_DEBUG_DISPLAY to true on a production site. Displaying PHP errors publicly reveals file paths, plugin names, and other information that attackers can use.

Where to Find the Debug Log File

Once debug mode is enabled, WordPress creates (or appends to) a file at:

/wp-content/debug.log

You can access this file through FTP, your hosting file manager, or SSH. Some managed hosting providers also expose error logs through their dashboard, though the location may differ.

If the file doesn’t appear after enabling debug mode, check that your wp-content directory has write permissions (typically 755 for the directory). If it still doesn’t appear, there may be no errors to log — which is actually good news.

How to Read the Debug Log

Open debug.log in any text editor. Each entry includes a timestamp, the error severity, a description, and the file and line number where the error occurred. Here’s a typical entry:

[15-Mar-2026 14:32:07 UTC] PHP Warning: Undefined variable $thumbnail in /home/user/public_html/wp-content/plugins/example-plugin/includes/display.php on line 142

Breaking this down:

  • Timestamp: When the error occurred.
  • Severity: “PHP Warning” — more serious than a notice, less critical than a fatal error.
  • Description: “Undefined variable $thumbnail” — the actual problem.
  • Location: The specific plugin file and line number causing the issue.

Error Severity Levels

Not all debug log entries are equally urgent. Understanding the severity levels helps you prioritize:

  • PHP Fatal Error: The most serious. Something broke completely, and a page or function stopped working. Fix these immediately.
  • PHP Warning: Something isn’t working as expected, but the site continues to function. These can cause subtle bugs and should be addressed.
  • PHP Notice: Minor issues like undefined variables. Often caused by sloppy coding in plugins or themes. Not urgent but worth noting.
  • PHP Deprecated: A function being used is outdated and will be removed in a future PHP version. Important for long-term compatibility.
  • WordPress Database Error: A database query failed. Could indicate corrupted tables, plugin conflicts, or performance issues.

Common Debug Log Errors and What They Mean

Certain errors appear in debug logs more frequently than others. Here’s how to interpret the most common ones:

Undefined Variable or Index

PHP Notice: Undefined variable: post_meta in /wp-content/plugins/example/functions.php on line 89

A plugin or theme is trying to use a variable that hasn’t been set. This is usually a coding oversight and rarely causes visible issues, but it indicates the code quality isn’t great. If you see these from a plugin you rely on, check for updates or consider alternatives.

Cannot Modify Header Information

PHP Warning: Cannot modify header information - headers already sent by (output started at /wp-content/plugins/example/init.php:1)

This means something (usually a plugin) output content before WordPress was ready. Common causes are extra whitespace or a BOM character at the beginning of a plugin file. This error often causes redirect issues or problems with downloads.

Allowed Memory Size Exhausted

PHP Fatal Error: Allowed memory size of 67108864 bytes exhausted

WordPress ran out of memory. This can happen with memory-intensive plugins, large image uploads, or insufficient server resources. You can increase the memory limit in wp-config.php with define('WP_MEMORY_LIMIT', '256M'); but if the error persists, investigate what’s consuming so much memory. Our guide on diagnosing a slow website covers memory and performance troubleshooting in depth.

Call to Undefined Function

PHP Fatal Error: Uncaught Error: Call to undefined function example_function() in /wp-content/themes/mytheme/functions.php:45

The code is calling a function that doesn’t exist. This usually happens when a required plugin is deactivated, a theme dependency is missing, or an update removed a function. Check that all required plugins are active and updated.

Using the Debug Log to Troubleshoot Plugin Conflicts

Plugin conflicts are one of the most common causes of WordPress problems, and the debug log is your best tool for identifying them. Here’s a systematic approach:

  1. Enable debug logging using the wp-config.php constants described above.
  2. Clear the existing debug.log file (or note the current timestamp) so you’re only looking at new errors.
  3. Reproduce the problem — visit the page that’s broken, trigger the action that fails.
  4. Check the debug log for new entries. The file path in each error tells you which plugin or theme is involved.
  5. Deactivate the suspected plugin and test again. If the error stops, you’ve found the culprit.
  6. Check for updates to the problematic plugin. Many errors are fixed in newer versions.

For thorough conflict testing, a staging site lets you deactivate plugins and test changes without risking your live site. Keeping plugins updated is also preventive medicine — our guide to managing plugin updates covers the safe way to stay current.

Advanced Debug Log Techniques

Custom Debug Logging

Developers can write custom messages to the debug log using PHP’s error_log() function:

// Log a simple message
error_log( 'Custom message: function X was called' );

// Log a variable's value
error_log( print_r( $my_variable, true ) );

This is invaluable when debugging custom code or trying to understand the order of operations during page loads. Just remember to remove custom logging statements when you’re done troubleshooting.

Database Query Debugging

To log database queries, add this constant to wp-config.php:

define( 'SAVEQUERIES', true );

This saves every database query, how long it took, and which function called it. You can then inspect the $wpdb->queries array to identify slow queries. This is particularly useful for database optimization work, but be aware that enabling this on a production site impacts performance — use it temporarily and on staging when possible.

Script Debug Mode

define( 'SCRIPT_DEBUG', true );

This forces WordPress to use the unminified versions of CSS and JavaScript files. It’s useful when debugging front-end issues because error messages in unminified files are more readable and point to the actual line of code causing problems.

Managing the Debug Log File

The debug log grows over time and can become very large on busy sites. A few management tips:

  • Check the file size periodically. A debug log growing by megabytes per day indicates serious issues that need attention.
  • Clear the log after resolving issues. Delete or empty the file so new problems are easy to spot.
  • Disable debug mode when not actively troubleshooting. On production sites, leaving debug mode enabled unnecessarily can impact performance and create large log files.
  • Restrict access to the log file. Add a rule to your .htaccess file to prevent public access: <Files debug.log> Order allow,deny Deny from all </Files>

Debug Log Plugins for Non-Technical Users

If editing wp-config.php feels uncomfortable, several plugins provide a dashboard interface for debug logging:

  • WP Debugging: Enables debug constants with a toggle — no file editing required.
  • Query Monitor: A developer tools panel that shows database queries, PHP errors, hooks, and more right in your admin bar. Excellent for developers.
  • Debug Bar: Adds a debug menu to the admin bar showing query, cache, and other debugging information.
  • Error Log Monitor: Displays debug log contents in the WordPress dashboard with filtering and search.

These plugins make debugging more accessible, but remember to deactivate them on production sites when you’re not actively troubleshooting.

Frequently Asked Questions

Is it safe to leave debug mode on in production?

It’s safe if WP_DEBUG_DISPLAY is set to false, but not ideal. Debug logging adds minor overhead and the log file grows continuously. Enable it for troubleshooting, then disable it when you’re done. If you need ongoing error monitoring, use a plugin like Query Monitor that can be toggled on and off easily.

Can visitors see the debug log?

By default, debug.log is accessible by direct URL if someone knows the path. Protect it by adding an .htaccess rule to deny access, or move the log file to a location outside your web root by defining a custom path: define('WP_DEBUG_LOG', '/path/outside/webroot/debug.log');

My debug log is full of notices from plugins I use. Should I worry?

PHP notices are the least severe error type and often don’t cause visible issues. However, they indicate code that isn’t following best practices. If a plugin generates excessive notices, check if an update resolves them. If not, it may be worth considering a better-maintained alternative.

How do I debug issues that only happen intermittently?

Enable debug logging and leave it running (with display off) until the issue occurs again. Check the debug log timestamps to correlate errors with the time the problem appeared. For issues related to high traffic or specific conditions, combining the debug log with server access logs often reveals the pattern.

Start Troubleshooting Smarter

The WordPress debug log turns guesswork into data. Instead of randomly deactivating plugins or searching forums for hours, the debug log tells you exactly what’s failing and where. Enable it, learn to read it, and you’ll solve WordPress problems faster and with more confidence.

Dealing with persistent WordPress issues you can’t resolve? Book a free consultation and our team will help diagnose and fix what’s going wrong.