How to Enable WP_DEBUG and Actually Read the WordPress Log

Something's broken on your WordPress site — a blank patch on a page, a plugin that silently refuses to save settings, an import that dies halfway through — and the front end gives you nothing to work with. No error, no clue, just a gap where content should be. This is the guide for that moment: how to turn WordPress's own logging on, where the log file actually lives, and how to read it like someone who's done this a hundred times.

Symptom: WordPress fails quietly

By default, a production WordPress install is configured to swallow errors rather than show them. That's deliberate — you don't want a fatal PHP notice dumping a file path and server details in front of a visitor. But it means the person actually trying to fix the problem (you) is just as blind as everyone else. The fix isn't guesswork or reinstalling plugins one by one until something changes. It's turning on the logging that's already built into WordPress core and reading what it tells you.

Why the errors are hidden by default

Two settings control this, and they're easy to confuse. display_errors is a PHP-level setting that controls whether errors print directly to the page. WP_DEBUG is a WordPress-level switch that controls whether WordPress even generates the extra notices and deprecation warnings in the first place. On a healthy production site, both are effectively off — PHP errors are suppressed and WordPress isn't logging much beyond fatal crashes. To debug properly, you need to flip WordPress's logging on without exposing anything to the public front end. That's the whole trick.

Step 1: Turn on WP_DEBUG the right way

Open wp-config.php in File Manager (or over SFTP) and find the line that says /* That's all, stop editing! Happy publishing. */. Everything you add has to go above that line, or WordPress ignores it. If WP_DEBUG is already defined further up the file (most installs have define('WP_DEBUG', false); by default), edit that line instead of adding a second one — a duplicate constant definition throws its own fatal error.

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

Here's what each line actually does:

That last @ini_set line is a belt-and-braces move — some server configs override WP_DEBUG_DISPLAY at the PHP level, and this makes sure nothing leaks onto the page regardless.

Two more constants worth knowing

If the bug is inside a theme or a script/style enqueue and not showing up yet, add define( 'SCRIPT_DEBUG', true ); — it forces WordPress to load the unminified core JS and CSS, which makes browser console errors point at real line numbers instead of a minified blob. And if a page feels slow rather than broken, define( 'SAVEQUERIES', true ); logs every database query WordPress runs on that load, viewable through Query Monitor (more on that below). Leave both off unless you're actively chasing that specific class of problem — they add overhead.

Step 2: Find and read wp-content/debug.log

Once WP_DEBUG_LOG is on, reload the page that's broken. WordPress creates the file the first time it has something to write, at:

/wp-content/debug.log

In cPanel, open File Manager, navigate to public_html/wp-content/ (or your site's subfolder for an addon domain), and enable "Show Hidden Files" if you don't see it — some setups don't hide it, but it's worth checking. On a VPS over SSH, tail it live while you reproduce the issue:

tail -f /var/www/yoursite/wp-content/debug.log

Reproduce the problem — load the page, submit the form, run the import — then stop and read the newest lines at the bottom of the file.

Step 3: Decode what you're actually looking at

Log lines look cryptic at first, but they follow a consistent pattern: a timestamp, a severity level, then the message and file path. Here's how to triage by severity:

The single most useful piece of information in any line is the file path right after "in" — it almost always sits inside wp-content/plugins/<plugin-name>/ or wp-content/themes/<theme-name>/, which tells you exactly what to deactivate to confirm the cause.

Step 4: When debug.log stays empty

If nothing shows up after you reproduce the error, the problem is happening at a level WordPress never gets to log — a server-level PHP fatal, or a request that's being blocked before PHP even runs. Check the server's own PHP error log instead:

• cPanel shared hosting: WHM/cPanel usually writes to /home/username/public_html/error_log — check File Manager in the site root, not just wp-content.
• A VPS running PHP-FPM: /var/log/php8.2-fpm.log (adjust the version number to match yours).
• Nginx front end: /var/log/nginx/error.log will show 502/504 gateway errors that never reach WordPress at all.

A completely empty log everywhere, paired with a genuinely blank page, often means a caching plugin or full-page cache (Cloudflare, LiteSpeed Cache, Varnish) is serving a stale cached copy of the broken page. Purge cache before you assume the debug setup is broken.

Step 5: Query Monitor — the readable version of all this

Reading raw log files gets old fast. Install the free Query Monitor plugin and it puts a toolbar in the admin bar showing PHP errors, slow database queries, hook calls, and enqueued scripts for the exact page you're viewing — no tailing files required. It respects your current user's capabilities, so it's reasonably safe to leave installed (though not activated for every visitor) even after you're done troubleshooting.

Prevention: don't leave this running on a live site

Once you've found and fixed the issue, turn WP_DEBUG back to false in wp-config.php. Leaving it on doesn't expose data to visitors by itself — WP_DEBUG_DISPLAY handles that — but the log file itself keeps growing, and a large debug.log sitting in a publicly-reachable folder is a real information leak if someone finds the URL directly. Delete or archive it after each debugging session, and never commit it to a git repo if you're using version control for your theme or plugin code.

FAQ

Do I need SSH access to do this?

No. Everything here works through cPanel's File Manager — editing wp-config.php and viewing debug.log are both point-and-click. SSH just makes tailing the log live a little faster if you have it.

Is it safe to leave WP_DEBUG on all the time?

Not on production. With WP_DEBUG_DISPLAY set to false it won't leak to visitors, but the log file grows indefinitely and every request pays a small performance cost generating those extra notices. Turn it on to diagnose, then turn it off.

The file wp-content/debug.log never appears at all. Why?

Usually a file permissions issue — the web server user needs write access to wp-content/. It can also mean a syntax error in your wp-config.php edit is preventing WordPress from loading at all; double-check you added the lines above the "stop editing" comment and didn't duplicate an existing WP_DEBUG line.

Can I read the log without exposing it to the public?

Yes — by default nothing outside wp-content links to it, but it's not access-controlled either. Add a rule blocking direct access to *.log files in your .htaccess (or Nginx config) as a precaution, especially if you forget to delete it after debugging.

What's the difference between this and my hosting provider's error log?

debug.log is WordPress-specific — plugin and theme code, database query issues, deprecated function calls. The server-level PHP error log (Step 4) catches lower-level fatals, including ones that happen before WordPress finishes loading, which debug.log never sees.