Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 68 ยท Getting Started

Debugging WordPress

Learn to debug WordPress. Use WP_DEBUG, WP_DEBUG_LOG, SCRIPT_DEBUG and SAVEQUERIES, read debug.log, fix the white screen of death and isolate a bad plugin safely.

By default WordPress hides PHP errors, because showing them to visitors is both ugly and a security leak. That is fine in production and terrible while developing: a typo gives you a blank white page and no clue why. The first thing you should do on any development site is switch on debugging, so that notices, warnings and fatal errors are recorded where you can read them.

This lesson covers the real debug constants (read-only config snippets), the tools that help you find slow queries, and a repeatable method for tracking down the plugin or theme that broke your site. The runnable examples are plain-PHP stand-ins: an error logger with severity levels and a plugin-isolation routine.

The debug constants

All of these go in wp-config.php, above the line that loads wp-settings.php. This is the recommended development setup, shown read-only:

PHP
<?php
define( 'WP_DEBUG', true );          // Turn on debugging
define( 'WP_DEBUG_LOG', true );      // Write errors to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // Do not print errors into the page
define( 'SCRIPT_DEBUG', true );      // Use unminified core CSS and JS
define( 'SAVEQUERIES', true );       // Remember every database query

What each one does:

Constant Effect Typical value in development
WP_DEBUG Master switch. Enables PHP notices, warnings and deprecation messages in WordPress code. true
WP_DEBUG_LOG Writes errors to wp-content/debug.log. It can also be set to a custom file path. true
WP_DEBUG_DISPLAY Controls whether errors are printed in the page. Turn it off when errors break JSON or AJAX responses. false (or true for quick local work)
SCRIPT_DEBUG Loads non-minified core scripts and styles, so JavaScript errors point at readable lines. true when debugging scripts
SAVEQUERIES Stores each query with its time and caller in $wpdb->queries. It uses memory, so never leave it on in production. true temporarily

On a production site keep WP_DEBUG off, or if you must log, set WP_DEBUG_LOG to true and WP_DEBUG_DISPLAY to false, and make sure debug.log is not publicly readable. Its contents can include file paths and sometimes data.

Reading debug.log

With logging on, each problem becomes a line like this (shown read-only):

TEXT
[12-Mar-2025 10:04:11 UTC] PHP Warning:  Undefined array key "price" in /wp-content/plugins/shop/cart.php on line 42
[12-Mar-2025 10:04:11 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function acme_total() in /wp-content/themes/my-theme/functions.php:88

Read it from the bottom up: the newest entry is last. Each line gives a severity, the message, the file and the line. The file path tells you whose code is at fault: plugins/shop/ means the Shop plugin, themes/my-theme/ your theme. You can write your own entries with error_log():

PHP
<?php
error_log( 'Cart total was ' . $total );
error_log( print_r( $order_data, true ) );   // arrays and objects

Remember to delete such lines when you are done.

flowchart LR
    A["PHP error or<br/>error_log() call"] --> B{"WP_DEBUG<br/>on?"}
    B -->|no| X["Hidden"]
    B -->|yes| C{"WP_DEBUG_LOG?"}
    C -->|yes| D["wp-content/debug.log"]
    B -->|yes| E{"WP_DEBUG_DISPLAY?"}
    E -->|yes| F["Printed in the page"]

Debugging output can go to a log file, the page, both or neither, depending on the three constants.

Try it: a tiny error logger

The stand-in below mimics what logging does: it has severity levels, a minimum level (the "debug mode" switch) and an in-memory "file". Notice how raising the threshold hides low-severity messages, just as production hides notices.

PHP A leveled error logger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Finding slow queries

Not every problem is an error. A page may simply be slow. Two tools help:

  • SAVEQUERIES records every query in $wpdb->queries, each with SQL, time and the call stack. You can loop over it in a temporary debug snippet to print the slowest ones.
  • Query Monitor is a free plugin and the standard answer. Its toolbar shows the number and time of queries, flags duplicates and slow ones, shows which plugin or theme file caused each, lists hooks, HTTP requests and PHP errors. Install it on development sites; it becomes your most-used debugging tool.

You will use these properly in Performance Optimization.

The white screen of death

A blank page with no message is usually a PHP fatal error with display switched off. Common causes:

  • A plugin or theme with a syntax error or a missing function.
  • A plugin that needs a newer PHP version than the server runs.
  • Running out of PHP memory (Allowed memory size exhausted in the log).
  • A bad edit to functions.php or wp-config.php.

Since WordPress 5.2 you may also see the message "There has been a critical error on this website", often with an email to the admin that includes a recovery mode link, which lets you log in with the broken plugin paused. In any case, the first step is the same: turn on WP_DEBUG_LOG and read debug.log.

Isolating a plugin or theme

If the log is unclear, isolate the cause by elimination. Do this on a copy of the site or a development machine, never experimentally on a busy live site:

  1. Deactivate all plugins. If the site works, a plugin is the cause. If you cannot reach the dashboard, rename wp-content/plugins to plugins-off.
  2. Reactivate plugins one at a time, reloading each time, until the problem returns. The last one is your suspect.
  3. If plugins are innocent, switch to a default theme such as the newest "Twenty Twenty-..." theme.
  4. Check for conflicts between two plugins by testing the suspect with only one other active at a time.

Computers are good at this, so here is the same procedure as a binary search, which needs far fewer reloads than one-by-one when you have many plugins. The stand-in finds the single faulty plugin and counts how many "reloads" it took.

PHP Find the culprit plugin by bisecting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

With 12 plugins, bisecting needs 4 reloads. Change $culprit to another plugin to check that it still finds it.

Good habits

  • Develop with WP_DEBUG on, always. A site that is clean under WP_DEBUG is far less likely to break after an update.
  • Fix deprecation notices when you see them; they warn about code that will stop working.
  • Check debug.log after every change to a plugin or theme.
  • Delete or rotate debug.log regularly; it grows forever.
  • Never leave display_errors on for visitors, and never post a full debug.log publicly when asking for help; it can contain paths and secrets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which combination is recommended for a typical development site?

    Debugging on, errors written to debug.log, and not printed into pages (which can break AJAX/JSON output and leak details).
  2. 2. What does SCRIPT_DEBUG do?

    SCRIPT_DEBUG loads the readable core files. SAVEQUERIES is the constant that records queries.
  3. 3. A page is completely blank after you activate a plugin. What is the best first step?

    A blank page is usually a hidden fatal error. The log tells you the file and line responsible.
  4. 4. Why should SAVEQUERIES not stay on in production?

    Recording every query is useful temporarily, but the overhead is wasteful on a live site.

Summary

  • Enable WP_DEBUG and WP_DEBUG_LOG in development and keep WP_DEBUG_DISPLAY off; read wp-content/debug.log from the bottom up.
  • SCRIPT_DEBUG loads unminified core assets; SAVEQUERIES records queries and is for temporary use.
  • Query Monitor shows slow queries, duplicates, hooks and the plugin responsible.
  • The white screen is usually a hidden fatal error: read the log, or use recovery mode.
  • Isolate faulty plugins by deactivating all and reactivating step by step, or bisecting.

Next up: The WordPress Database Schema.