How to Debug WordPress — The Complete WP_DEBUG, Error Log, and Query Monitor Guide

WordPress debug mode is a built-in diagnostic system that reveals hidden PHP errors, warnings, and performance issues on your site — and learning how to debug WordPress is the single most important troubleshooting skill any site owner can have. This guide walks you through enabling WP_DEBUG, reading error logs, and using Query Monitor to find and fix problems fast.

What Is WordPress Debug Mode and Why You Need It

800×450

WordPress is polite by default. Too polite. Out of the box, it swallows PHP errors whole and serves you a clean page — or a cryptic white screen — with zero explanation. Debug mode tears that mask off. When you know how to debug WordPress, you stop guessing and start reading actual error data.

At a technical level, WP_DEBUG is a PHP constant you define in wp-config.php. Setting it to true tells WordPress to stop suppressing PHP errors, warnings, and notices. Everything that was silently failing now announces itself. It is exactly what you need when a plugin update tanks your site or a theme customization goes sideways.

That stat should make your stomach drop. Nearly half of disclosed plugin vulnerabilities had no fix available. If something breaks on your site — or something gets exploited — you need to know how to debug WordPress well enough to investigate the damage yourself. After a messy plugin update forces you to troubleshoot, you’ll want to know how to update WordPress safely so you’re never caught off guard again.

The Five WordPress Debug Constants Explained

800×450

Most articles tell you to flip WP_DEBUG and call it a day. That is amateur hour. There are five constants in the WordPress debug system and each one does something different. Know all five and you actually know how to debug WordPress properly.

WP_DEBUG — The Master Switch

WP_DEBUG activates the entire debug system. Set it to true and WordPress surfaces every PHP error, warning, notice, and deprecated function call on your site. Set it to false (the default) and everything gets buried. This is your starting point every single time you need to debug WordPress.

WP_DEBUG_LOG — Save Errors to a File

WP_DEBUG_LOG tells WordPress to write all errors to a log file instead of — or in addition to — displaying them. When set to true, errors go to /wp-content/debug.log. You can also pass a custom file path as a string. This is how you capture errors quietly without blasting them across your screen.

WP_DEBUG_DISPLAY — Show or Hide Errors on Screen

WP_DEBUG_DISPLAY controls whether PHP errors print directly on your web pages. The recommended setup: set this to false so errors get logged silently instead of appearing for every visitor. Always pair this with WP_DEBUG_LOG true or your errors vanish into the void.

SCRIPT_DEBUG — Load Unminified Core Files

SCRIPT_DEBUG forces WordPress to load full, unminified versions of core CSS and JavaScript. Minified files are compressed for speed — great for production, terrible for debugging. When a frontend script is misbehaving, flip this to true so you can actually read what the code is doing.

SAVEQUERIES — Track Database Queries

SAVEQUERIES stores every database query in a global array so you can inspect them. It is a blunt instrument — it adds overhead — but when you suspect a slow plugin is hammering your database, this constant exposes exactly what’s running. Use it in staging only, and kill it when you’re done.

How to Enable WordPress Debug Mode in wp-config.php

800×450

The manual method is the right method. Plugins that toggle debug mode are fine for beginners, but knowing the raw code means you can debug WordPress even when your admin panel is inaccessible — which is exactly when you’ll need it most.

Access your wp-config.php file via FTP or your host’s file manager. It lives in your WordPress root directory. If you’ve never touched it before, read our guide on what wp-config.php is and how to edit it before you proceed — that file runs your entire site.

Add this block of code before the line that reads /* That's all, stop editing! Happy publishing. */:

// Enable WordPress debug mode
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

As the official WordPress developer documentation puts it: “It is not recommended to use WP_DEBUG or the other debug tools on live sites; they are meant for local testing and staging installs.” That is not a suggestion. That is policy. Follow it.

How to Enable Debug Mode With a Plugin

800×450

If you want to learn how to debug WordPress without touching config files, the plugin route works. Two solid free options exist for this.

WP Debugging is the most direct option. Install it, activate it, and it flips WP_DEBUG and WP_DEBUG_LOG on automatically. No file editing required. It also adds a debug bar to your admin panel so you can see notices without digging through log files.

Debug Log Manager gives you a cleaner UI for managing your debug.log file from inside WordPress. You can view, clear, and download the log without FTP. Good option when you need to hand debug access to a client or a non-technical team member.

Plugin vs manual when deciding how to debug WordPress: use plugins for quick investigations on staging. Use manual code when you need full control, when your site is broken before WordPress fully loads, or when you need SCRIPT_DEBUG and SAVEQUERIES alongside the basic flags. If you need to debug WordPress at depth, the plugin approach has a ceiling.

How to Read and Interpret the Debug Log

800×450

Once you know how to debug WordPress at the config level, the next step is reading what the log actually says. This is where every other guide abandons you. Enabling the log is step one. Reading it is the actual skill. Here is how to debug WordPress by actually understanding what the log is telling you.

Find your debug.log file at /wp-content/debug.log. Open it in any text editor. Each entry starts with the error type, followed by a message, followed by the file path and line number where the problem occurred. That file path is your lead — it tells you exactly which plugin or theme is misbehaving.

The four error types you will see most often, ranked by severity:

• Fatal error — Execution stopped. Something broke hard. Usually a missing function or class.
• Warning — Code continued but something is wrong. Often a missing file or bad function argument.
• Notice — Minor issue, not necessarily broken. Undefined variables, deprecated calls.
• Deprecated — A function that still works but will be removed in a future version. Fix it before it becomes a Fatal.

A real-world log entry looks like this:

[07-Apr-2026 14:23:01 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_field() in /wp-content/themes/my-theme/functions.php on line 47

Translation: the theme is calling get_field() — which belongs to Advanced Custom Fields — but ACF isn’t active. The fix is right there in the log. Stack traces work the same way: read from the top error down through the chain of function calls to find where the problem originated. When you know how to debug WordPress this way, you stop googling generic error messages and start solving actual problems.

Using Query Monitor to Debug WordPress

800×450

Query Monitor is the best free debugging tool in the WordPress ecosystem. Install it, activate it, and a debug menu drops into your admin bar on every page. No configuration required. This is how to debug WordPress visually, in real time, without touching a log file.

Debugging Database Queries

Query Monitor shows you every database query executed on a page request — how many ran, how long each took, and which plugin or theme triggered each one. A page spawning 300+ queries has a problem. This panel names the guilty party directly so you know how to debug WordPress performance issues without guessing.

Debugging PHP Errors and Warnings

To learn how to debug WordPress errors visually, the Logs panel inside Query Monitor captures all PHP errors in a clean table — type, message, file, and line number. It is the same information as your debug.log file but presented in a readable, sortable interface. Much faster when you’re actively iterating on a fix.

Debugging Hooks and Actions

For those learning how to debug WordPress hooks, the Hooks panel shows you every action and filter that fired during a page request, along with which callbacks are attached and in what priority order. If you’ve ever been confused about why a hook isn’t firing or why something is running twice, this panel gives you the answer instantly. For deeper context on how the hook system works, our WordPress hooks, actions, and filters guide breaks it all down.

Debugging HTTP API Calls

Understanding how to debug WordPress HTTP calls is critical. The HTTP API Calls panel logs every external request your site makes — remote calls to APIs, license servers, update checks. If a plugin is making dozens of external calls on every page load, you will see it here. That is often the source of slow page load times that have nothing to do with your database. For full Query Monitor documentation, see the official Query Monitor usage guide.

Debugging Common WordPress Errors

800×450

Theory is useless without application. Here is how to debug WordPress when you hit the four most common disasters:

White Screen of Death (WSOD)

When you need to know how to debug WordPress through a white screen, start here. A blank white screen means PHP died before WordPress finished rendering the page. Enable WP_DEBUG_LOG immediately and check debug.log — you will almost always find a fatal error pointing to a plugin or theme file. If you can’t access the admin, deactivate plugins manually by renaming the /wp-content/plugins/ folder via FTP.

500 Internal Server Error

Understanding how to debug WordPress 500 errors starts with ruling out the basics. A 500 error can be PHP, server configuration, or a corrupted .htaccess file. Start with your server’s error log (not WordPress’s debug log — your host’s actual PHP error log). If that’s clean, enable WP_DEBUG and reload. Try regenerating .htaccess by re-saving your permalink settings.

“Critical Error” Email Notification

Knowing how to debug WordPress critical errors is essential. When WordPress detects a fatal error, it emails the admin address and displays “There has been a critical error on your website.” This is WordPress’s built-in recovery mode. Click the link in the email to access the admin in safe mode, then check the error details to identify which plugin or theme caused it.

Plugin Conflicts

Plugin conflicts are the most common reason to learn how to debug WordPress at all. When figuring out how to debug WordPress plugin conflicts, the workflow: enable WP_DEBUG_LOG, then deactivate all plugins. If the problem stops, reactivate them one by one and reload the page after each activation. The one that breaks the site is your culprit. Query Monitor’s error panel makes this process twice as fast.

WordPress Debugging Best Practices

800×450

Knowing how to debug WordPress is only half the battle. Doing it without blowing up your live site is the other half. Follow these rules.

• Always debug on staging, never on production. Your live site has real visitors. Debug mode exposes file paths, server info, and error details that attackers actively look for. Set up a WordPress staging environment and do all your debugging there.
• Disable debug mode when you’re done. Set WP_DEBUG back to false the moment you’ve identified your issue. Do not leave it running “just in case.”
• Secure your debug.log file. Add this to your .htaccess to block public access to the log: <Files debug.log> Order allow,deny Deny from all </Files>
• Use version control. When you know how to debug WordPress with version control, Git means you can see exactly what changed between “working” and “broken.” Debugging without version control is fighting with one hand tied behind your back.
• Read the official docs. The WordPress developer documentation on debugging is the canonical reference — it covers every constant and edge case in plain detail.

Frequently Asked Questions

Now You Know How to Debug WordPress — Stop Waiting for Help Tickets

You now know how to debug WordPress from top to bottom — and you have the complete toolkit. Five debug constants, a step-by-step method to enable them, a full walkthrough of how to read your error log, and Query Monitor as your real-time diagnostic cockpit. There is no WordPress error you cannot at least investigate with these tools in your hands.

Knowing how to debug WordPress yourself is what separates site owners who panic from site owners who fix things. When you know how to debug WordPress, every plugin conflict, every white screen, every 500 error — they all leave evidence. You just needed to know where to look and how to read what you find.

One last thing: Now that you know how to debug WordPress, bookmark our WordPress tools arsenal for the full stack of resources the pirates use to build, maintain, and troubleshoot WordPress sites without paying SaaS companies for things WordPress already does for free.

What’s the nastiest WordPress error you’ve ever had to debug? Drop it in the comments — tell us the error, the cause, and how long it took you to find it. If you had WP_DEBUG enabled, it probably took minutes. If you didn’t — well, that’s why you’re here now.