WordPress Debugging: Enabling WP_DEBUG and Reading Error Logs

Table of Contents

Introduction

Learn how to enable WP_DEBUG in WordPress, read error logs, and diagnose issues like a pro. This guide will turn your debug.log into a powerful troubleshooting tool.

When your WordPress site throws a white screen, shows cryptic errors, or a plugin suddenly breaks, you need to know what’s going on under the hood. Think of debug.log as a black box recorder for your WordPress site—it captures what happened when things went wrong. In this article, you’ll learn how to enable WP_DEBUG, configure it safely, and interpret the messages it produces. By the end, you’ll be able to track down the root cause of many common WordPress issues on your own.

Why WordPress Debugging Matters

Debugging tools give you visibility into what’s really happening when your site misbehaves—instead of guessing, you get answers.

A WordPress site without debugging enabled is like driving with a blindfold: when something breaks, you have no idea why. The White Screen of Death? A plugin conflict? A deprecated function? Without WP_DEBUG and debug.log, you’re left to trial and error—deactivating plugins one by one, hoping to stumble on the culprit. Enabling WordPress debugging changes that. It reveals PHP errors, warnings, and notices that point directly to the file, line, and cause of the problem. Whether you’re troubleshooting a 404, a plugin crash, or a theme conflict, having access to error logs puts you in control. It’s one of the first skills any serious WordPress user or developer should master.

Before You Start: Safety First

Always prepare before editing wp-config.php—a backup and staging environment can save you from costly mistakes.

Editing wp-config.php is a low-risk operation when done correctly, but it’s still a core configuration file. A typo or misplaced character can take your site offline. Before you enable WP_DEBUG, make sure you’ve covered the basics:

Backup your site: Use a plugin like UpdraftPlus or your host’s backup tool. Include both files and the database.
Use staging if possible: Many hosts offer staging environments. Test debugging there first, especially on production sites.
Have FTP or File Manager access: You’ll need to edit wp-config.php and possibly download debug.log. Ensure you can reach your site’s files.

Important: Never enable WP_DEBUG on a live site without a backup. If something goes wrong during editing, you’ll want a quick way to restore your site to a working state.

Enabling WP_DEBUG in wp-config.php

Adding a few lines to wp-config.php is all it takes to turn on WordPress debugging and start logging errors.

The wp-config.php file lives in your WordPress root directory—the same folder that contains wp-admin, wp-content, and wp-includes. Here’s how to enable debugging step by step:

Locate wp-config.php: Connect via FTP, SFTP, or your host’s File Manager. Navigate to the root of your WordPress installation.
Download a backup: Before editing, download a copy of wp-config.php to your computer. If anything goes wrong, you can re-upload it.
Open the file in a text editor: Use a plain text editor (Notepad++, VS Code, Sublime Text). Avoid Word or rich text editors—they can corrupt the file.
Find the line that says: define( 'WP_DEBUG', false ); (or a similar debug-related line). If it doesn’t exist, look for the line /* That's all, stop editing! Happy blogging. */.
Add the following code before that line:

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

Breaking it down: The first line turns on debug mode. The second sends all errors to a log file instead of the screen. The third and fourth lines prevent errors from appearing on your live site—visitors won’t see any debug messages. Errors will only be written to wp-content/debug.log, which you can review privately.

Understanding the Debug Constants

WordPress offers several debug-related constants—knowing what each one does helps you configure debugging for your situation.

WP_DEBUG: The master switch. When true, WordPress reports PHP errors, warnings, and notices. Required for any debugging.
WP_DEBUG_LOG: When true, errors are written to wp-content/debug.log. Essential for reviewing errors without showing them on screen.
WP_DEBUG_DISPLAY: When true, errors appear in the HTML of your pages. Set to false on live sites—you don’t want visitors or search engines to see internal errors.
SCRIPT_DEBUG: Loads unminified versions of WordPress core JS and CSS. Useful when debugging theme or plugin scripts. Optional for most users.
SAVEQUERIES: Saves all database queries to an array for analysis. Helpful for performance debugging but adds overhead—use only on staging.

Tip: For staging or development, use WP_DEBUG + WP_DEBUG_LOG + WP_DEBUG_DISPLAY set to false. For live sites when you need to troubleshoot, use the same but ensure you disable debugging as soon as you’re done.

WP_DEBUG Explained

WP_DEBUG is the main constant that activates WordPress’s debugging behavior. By default, PHP only shows fatal errors—the kind that produce a white screen. When you set WP_DEBUG to true, WordPress also reports warnings and notices. These are less severe but often point to deprecated functions, undefined variables, or code that doesn’t follow best practices. Catching them early helps prevent future breakage. For full details, see the official WordPress debugging documentation.

WP_DEBUG_LOG and WP_DEBUG_DISPLAY

WP_DEBUG_LOG writes errors to a file; WP_DEBUG_DISPLAY shows them in the browser. On a live site, you want logging but not display. Why? Errors that occur during AJAX requests, cron jobs, or admin actions may never appear on a page you’re viewing—they only show up in the log. If WP_DEBUG_DISPLAY is true, errors can also break your page layout, expose file paths, and look unprofessional to visitors. Keeping WP_DEBUG_DISPLAY set to false and relying on WP_DEBUG_LOG gives you the information you need without the downsides.

Example: Imagine a contact form that fails silently when submitted. The error might occur in an AJAX handler that runs in the background. You won’t see it on the page—but it will be recorded in debug.log. That’s why logging is essential even when display is off.

SCRIPT_DEBUG and SAVEQUERIES (Optional)

SCRIPT_DEBUG forces WordPress to load development versions of core JavaScript and CSS files instead of minified ones. If you’re debugging a conflict with WordPress core scripts, this can make stack traces and file references easier to read. SAVEQUERIES stores every database query WordPress runs, along with execution time. It’s invaluable for finding slow queries, but it adds noticeable overhead—your site will run slower. Use it only in a staging or local environment.

Did you know: SAVEQUERIES can significantly slow down your site because it records every single database call. Enable it only when you’re actively debugging database performance, and never leave it on in production.

Finding and Reading debug.log

Once WP_DEBUG_LOG is enabled, errors are written to wp-content/debug.log—here’s how to access and read it.

The debug.log file is created automatically in your wp-content folder the first time an error occurs. If you’ve just enabled debugging and don’t see it yet, trigger an error (for example, by visiting a broken page) and check again. To access the file:

Connect via FTP or File Manager: Use the same method you used to edit wp-config.php.
Navigate to wp-content: The log file is at wp-content/debug.log.
Download or view: You can download the file and open it in a text editor, or use your host’s File Manager to view it directly. Some hosts also show error logs in the control panel.
Clear when needed: The log grows over time. For a fresh start during troubleshooting, you can delete the file—WordPress will create a new one when the next error occurs.

Interpreting Common Error Messages

Understanding the types of errors in debug.log helps you prioritize and fix issues quickly.

WordPress and PHP use a few standard error levels. Here’s what you’ll typically see:

Fatal error: The script stops immediately. Often caused by a missing file, a syntax error, or a required function that doesn’t exist. Fix these first.
Warning: Something went wrong but execution continues. Could be a deprecated function, an undefined variable, or a file that couldn’t be opened. Warnings often lead to unexpected behavior.
Notice: Minor issues—undefined indexes, deprecated function usage. They may not break your site but indicate code that should be updated.
Deprecated: A function or argument that will be removed in a future WordPress version. Update your theme or plugin to use the recommended alternative.

A typical log entry looks like this: [04-Feb-2025 10:15:23 UTC] PHP Fatal error: Call to undefined function my_plugin_function() in /path/to/wp-content/plugins/my-plugin/my-plugin.php on line 42. The format tells you the date, error type, message, file path, and line number. Use that information to locate and fix the problem. Plugins like Query Monitor and Debug Bar can also surface errors in the WordPress admin bar, making them easier to spot without opening the log file.

Debugging Plugins as Alternatives

If you prefer not to edit wp-config.php, or want a friendlier interface, debugging plugins can help.

Debug Bar: Adds a debug menu to your admin bar. When WP_DEBUG is enabled, it shows PHP warnings and notices in a panel. Great for quick checks without opening the log file.
Query Monitor: Shows database queries, HTTP requests, and PHP errors in the admin bar. More comprehensive than Debug Bar—ideal for developers and power users.
WP Crontrol: Manages WordPress cron jobs. Useful when errors occur during scheduled tasks—you can run them manually and check the log.

Note: Most debugging plugins still require WP_DEBUG to be enabled in wp-config.php to capture errors. They add a layer of convenience on top of the built-in logging.

When to Disable Debugging

Debugging should be temporary—once you’ve identified and fixed the issue, turn it off.

Leaving WP_DEBUG enabled on a live site has downsides. It can slightly impact performance, and if WP_DEBUG_DISPLAY is ever accidentally set to true, sensitive information (file paths, database details) could be exposed to visitors. Search engines might also index error messages. After you’ve resolved the problem, set define( 'WP_DEBUG', false ); in wp-config.php and remove or comment out the other debug lines. Keep a backup of your debug configuration if you expect to need it again.

Important: Never leave WP_DEBUG set to true on a production site long-term. Use it for troubleshooting, then disable it. Your site will run more efficiently, and you’ll avoid potential security and SEO issues.

FAQ

1. What is WP_DEBUG and why should I use it?

Answer: WP_DEBUG is a WordPress constant that, when enabled, makes PHP report errors, warnings, and notices. You use it to diagnose problems—white screens, plugin conflicts, theme errors—by seeing exactly what went wrong and where. It’s essential for troubleshooting and development.

2. Is it safe to enable WP_DEBUG on a live site?

Answer: It’s safe if you set WP_DEBUG_DISPLAY to false and WP_DEBUG_LOG to true. Errors will be written to a log file only, not shown to visitors. Still, use it temporarily—enable it when troubleshooting, fix the issue, then disable it. Prefer a staging environment when possible.

3. Where is the debug.log file located?

Answer: The debug.log file is created in your wp-content directory, at wp-content/debug.log. It appears automatically once an error occurs after you’ve enabled WP_DEBUG_LOG. Access it via FTP, SFTP, or your host’s File Manager.

4. What’s the difference between WP_DEBUG_LOG and WP_DEBUG_DISPLAY?

Answer: WP_DEBUG_LOG writes errors to a file (debug.log); WP_DEBUG_DISPLAY shows them in the HTML of your pages. For live sites, use WP_DEBUG_LOG and set WP_DEBUG_DISPLAY to false so visitors never see error messages. You review the log privately instead.

5. How do I read and interpret error messages in debug.log?

Answer: Each line typically includes a timestamp, error type (Fatal error, Warning, Notice), the message, and the file and line number. Start with the file path and line—that’s where the problem originates. Fatal errors stop execution; warnings and notices may cause odd behavior. Fix fatals first, then address warnings.

6. Can I use a plugin instead of editing wp-config.php?

Answer: Plugins like Debug Bar and Query Monitor add a nicer interface for viewing errors, but they usually still require WP_DEBUG to be enabled in wp-config.php. There’s no way to fully enable WordPress debugging without editing that file. Plugins complement it; they don’t replace it.

7. What should I do if debug.log doesn’t appear?

Answer: First, confirm WP_DEBUG and WP_DEBUG_LOG are both set to true. Then trigger an error—visit a page that you know causes a problem, or temporarily add invalid code to a theme file. The log is created only when an error occurs. Check file permissions on wp-content; it must be writable by the web server.

8. When should I disable WP_DEBUG?

Answer: Disable it as soon as you’ve finished troubleshooting. There’s no need to keep it on once the issue is resolved. On production sites, long-term debugging can affect performance and, if misconfigured, expose sensitive information. Turn it off when you’re done.

Summary

Enable WP_DEBUG safely: Add the recommended constants to wp-config.php before “That’s all, stop editing!”—always use WP_DEBUG_LOG and set WP_DEBUG_DISPLAY to false on live sites.
Access debug.log: The file is at wp-content/debug.log. Use FTP or File Manager to download and read it.
Interpret errors: Focus on Fatal errors first, then Warnings and Notices. Use the file path and line number to locate the source.
Use plugins as helpers: Debug Bar and Query Monitor make errors easier to view but still require WP_DEBUG in wp-config.php.
Disable when done: Turn off WP_DEBUG after troubleshooting to avoid performance and security issues.

WordPress debugging is a powerful skill—once you know how to enable WP_DEBUG and read error logs, you can diagnose and fix many issues that would otherwise leave you stuck. Keep this guide handy, and you’ll be troubleshooting like a pro in no time.

How to Fix the WordPress White Screen of Death: Effective Solutions

Performance Optimization