How to Enable Debugging in WordPress

When a WordPress site misbehaves — a page errors out, a form stops sending, the admin won't load after an update — the cause is almost always written down somewhere. You just have to know where WordPress keeps the notes, and how to switch on more detailed recording without showing it to visitors.

Here's what to try first (no code), how to enable debug logging safely on a live site, and what to hand your developer.

Start here: Recovery Mode and Site Health

The old "white screen of death" — a blank page and no explanation — is mostly history. Since WordPress 5.2, a fatal error from a plugin or theme shows a "There has been a critical error on this website" message instead, and WordPress emails the site's admin address a recovery link. Click it and you're logged into a special Recovery Mode where the broken plugin or theme is paused, so you can deactivate it or roll it back. Check that inbox first (and spam) — that email usually names the file that failed.

Second stop: Tools → Site Health in the WordPress admin. It flags outdated PHP, missing modules, failed scheduled tasks, and plugin conflicts, and its Info tab shows your PHP version, memory limit, and whether debug settings are already on. Copy that Info report into any support ticket.

Ask your host before you touch anything

On managed WordPress hosting, the server is already logging PHP errors — the host just keeps that log outside your site's folders. Before editing config files, ask support for the last hour of your site's PHP error log. Often that alone answers "why did it break?" and you never change a thing.

The wp-config constants, explained

If you (or your developer) do need WordPress's own log, it's controlled by constants in wp-config.php, in the root of your install:

• WP_DEBUG — the master switch. Turns on error reporting.
• WP_DEBUG_LOG — true writes errors to wp-content/debug.log. You can also set it to a full path string to store the log somewhere private.
• WP_DEBUG_DISPLAY — whether errors print on the page. On a live site this must be false. Otherwise visitors (and search engines) see file paths and error text that reveal how your site is built.
• SCRIPT_DEBUG — loads the unminified versions of WordPress's core CSS and JavaScript. Only useful when chasing a front-end/JS problem.
• SAVEQUERIES — records every database query so a developer can find slow ones. It slows the site down noticeably; turn it on briefly, then off.
• WP_ENVIRONMENT_TYPE — declares whether a site is production, staging, development, or local. Well-behaved plugins and themes use it to change behaviour (for example, no live emails from staging). Your host may set this for you.

The safe configuration for a live site

Find the line /* That's all, stop editing! Happy publishing. */ and add this just above it. If a define( 'WP_DEBUG', ... ) line already exists, edit that one — a constant can only be defined once, and the first wins.

// Log errors to a file, but never show them to visitors
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );          // or a private path, e.g. '/home/you/logs/wp-errors.log'
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Optional, developer use only — remove when done
// define( 'SCRIPT_DEBUG', true );
// define( 'SAVEQUERIES', true );

Then reproduce the problem: load the broken page, submit the failing form, run the update again. Now the log has something to say.

Reading the log

Open wp-content/debug.log over SFTP or your host's file manager. Newest entries are at the bottom. Each line carries a timestamp, the type of problem (notice, warning, deprecated, fatal), and the file and line number where it happened.

What to look for:

• "PHP Fatal error" lines are the ones that actually break pages. Warnings and notices are clutter unless they repeat on every request.
• The same plugin or theme folder appearing over and over is your suspect. The path is right there in the entry.
• "Deprecated" means a plugin uses code that a newer PHP version has retired — usually a sign the plugin needs updating or replacing.

You don't need to interpret it yourself. Copy the last 20–50 lines and the Site Health Info report, and send both to your developer. That is a complete, useful bug report.

For developers: Query Monitor

The standard tool for digging deeper is the free Query Monitor plugin. It adds an admin-bar panel showing PHP errors, slow database queries, hooks, HTTP calls, and which plugin caused each — visible only to logged-in administrators. Install it for the investigation, remove it afterwards.

Turn it off when you're done

Leaving logging on forever has two costs: debug.log grows quietly until it fills disk space, and it stays in a web-accessible folder unless you moved it. Once the issue is fixed:

define( 'WP_DEBUG', false );

Remove any SCRIPT_DEBUG or SAVEQUERIES lines, and delete debug.log so stale entries don't mislead the next person. If your host offers a "debug mode" toggle in its own dashboard, use that instead of editing files — it does the same thing and remembers to switch itself off.