Debugging
Quick Definition
Debugging in WordPress means finding and fixing errors in your site. WordPress has built-in debug tools — WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY — that reveal PHP errors, warnings, and notices.
What Is Debugging?
Debugging is the process of finding and fixing errors in your WordPress site. When something breaks — a white screen, a broken feature, a plugin conflict — debugging tools help you figure out what went wrong and where.
WordPress has a built-in debugging system controlled by constants you set in wp-config.php. The three main constants are:
- WP_DEBUG — The master switch. Set to
trueto enable debug mode. This makes WordPress show all PHP errors, notices, and warnings that are normally hidden. - WP_DEBUG_LOG — Saves all errors to a log file at
wp-content/debug.log(or a custom path you specify). Requires WP_DEBUG to be enabled. - WP_DEBUG_DISPLAY — Controls whether errors appear on screen. Set to
falseto hide errors from visitors while still logging them to the file.
The recommended configuration for troubleshooting adds these three lines to wp-config.php, before the "stop editing" comment:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );This logs all errors to wp-content/debug.log without showing them to your visitors — the safest approach when debugging on a staging site.
WordPress also provides two additional debugging constants:
- SCRIPT_DEBUG — Forces WordPress to load the unminified (development) versions of its CSS and JavaScript files instead of the compressed versions. Useful when you are debugging front-end issues or testing modifications to core scripts.
- SAVEQUERIES — Stores every database query in the
$wpdb->queriesarray, including how long each took and which function called it. This is essential for diagnosing slow queries but adds overhead — only use it temporarily.
Important: Never leave WP_DEBUG enabled on a production site. Error messages can reveal file paths, database details, and other information that attackers can exploit. Debug on staging, fix on staging, then deploy to production.
Debugging in Practice
A typical debugging workflow looks like this: you notice a problem on your site, enable WP_DEBUG on your staging copy, reproduce the issue, then check wp-content/debug.log for the error message. The log tells you the exact file, line number, and error type — usually a PHP warning, a deprecated function notice, or a fatal error from a plugin or theme.
For more advanced debugging, plugins like Query Monitor (free) show database queries, hooks, HTTP requests, and PHP errors in a toolbar at the bottom of your screen. It is the most popular debugging tool in the WordPress ecosystem and does not require editing wp-config.php.
If you use WP-CLI, the wp eval and wp shell commands let you run PHP code directly in your WordPress environment — useful for testing functions without creating temporary plugin files.
Why It Matters
Every WordPress developer and site owner will encounter errors. Knowing how to enable debug mode, read the log file, and interpret error messages turns a stressful "my site is broken" moment into a methodical fix. It is the difference between guessing and knowing — and it is a fundamental skill for maintaining any WordPress site.