WordPress Debug Mode: How to Enable WP_DEBUG and Read the Debug Log (Step by Step)

Your site loads a blank white page. No error text, no content, just white. You refresh. Still white. Somewhere in your PHP, something broke. Maybe a plugin, maybe a theme, maybe a stray line of code. WordPress is hiding the reason from you.

WordPress debugging is how you make that hidden reason show up. Turn on the built-in debug mode. WordPress then reports the PHP errors, warnings, and notices it usually keeps quiet. This guide walks you through every switch.

You will learn what each constant does, how to turn them on safely, and where the log lands. Then you will learn to read it without panic. By the end you can catch a bug, trace it, and fix it. Your helpdesk team then spends less time guessing and more time helping customers.

TL;DR

What is WordPress Debugging?

WordPress debugging is the process of finding and removing errors in the PHP that runs your site. You may see it called WordPress debug mode, WP Debug, or the wp-debugger, but all three point to the same built-in tool. WordPress core, plugins, and themes are all written in PHP. When one of them fails, debug mode surfaces the error message. You get to read what went wrong, instead of staring at a blank screen.

The name says it plainly. A bug is an error in code, and de-bugging means taking that error out. Even skilled developers ship bugs, so this is normal maintenance work, not a sign that something is deeply broken.

PHP makes debugging feel more urgent than other languages. PHP runs on the server and builds your page before the browser sees it. If the PHP breaks, the page can stop loading and visitors get nothing. JavaScript runs after the page renders, so a JavaScript error can hide while the page still shows. That difference is why a PHP error often takes your whole site down. It is also why you need a reliable way to see it.

Debug mode gives you that visibility. Once it is on, WordPress reports every error, warning, and notice it finds. It even flags deprecated functions. Those still work today, but they break in a future PHP version.

What WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY Actually do

These three PHP constants control WordPress debugging. WP_DEBUG switches the whole mode on or off. WP_DEBUG_LOG saves errors to a file so you can review them later. WP_DEBUG_DISPLAY decides whether errors print on your pages or stay hidden. You set all three in wp-config.php, and they work together.

Here is what each one does on its own.

WP_DEBUG

WP_DEBUG is the master switch. Set it to true and WordPress displays all PHP errors, notices, and warnings, including deprecation notices for old functions. The default value is false, which is why a fresh install stays quiet. You flip it to true when you want to see what is happening under the hood.

WP_DEBUG_LOG

WP_DEBUG_LOG saves every reported error to a log file. By default WordPress writes to wp-content/debug.log. This matters because some errors never appear on screen. An error during an AJAX request, a WP-Cron run, or a REST API call happens off-page. A log is the only way to catch it. Set this constant to true and nothing gets lost.

WP_DEBUG_DISPLAY

WP_DEBUG_DISPLAY controls whether errors show inside your page HTML. The default is true, which prints errors right on the front end as they happen. On a live site that is a problem. Visitors see raw error text, your design breaks, and the message can leak details like file paths or a username. Set this to false to keep debugging on while hiding the mess from the public. Pair it with WP_DEBUG_LOG so the errors still land in your file. The official WordPress debugging documentation explains the same relationship between these constants.

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

To enable WordPress debug mode, edit the wp-config.php file in your site’s root folder and add the debug constants above the line that reads /* That's all, stop editing! Happy publishing. */. Placement matters. Constants added below that line will not load, so the debug mode never turns on.

Editing wp-config.php is the most reliable method because it works on any host, with no plugin and no dashboard toggle. It is also the method every host documents.

Where to Find wp-config.php

wp-config.php sits in the root folder of your WordPress install, the same folder that holds wp-admin and wp-content. Connect to your server with an FTP or SFTP client, or open your host’s file manager, and you will see it there. Some site owners move the file up one level for security, so check the parent folder if it is not in the root.

Before you touch it, make a backup. A 30-minute fix can turn into a 5-hour repair when a small typo in wp-config.php takes the site down. Save a copy of the file, or run a full backup, so you can roll back fast.

The Safe Production-Ready snippet

For a live site, you want errors logged but never shown to visitors. Add this block:

// Enable WP_DEBUG mode
define( 'WP_DEBUG', true );

// Enable Debug logging to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );

// Disable display of errors and warnings on the page
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

This turns debugging on, sends every error to wp-content/debug.log, and keeps the front end clean. The @ini_set( 'display_errors', 0 ) line is a belt-and-suspenders step that tells PHP itself to stop printing errors, in case a plugin flips display back on.

If you already see define( 'WP_DEBUG', false ); in the file, do not add a second copy. Change the existing false to true and add the other two lines beside it.

How to Enable the WordPress Debug Log and Find debug.log

To enable the WordPress debug log, set WP_DEBUG_LOG to true in wp-config.php while WP_DEBUG is also true. Once an error occurs, WordPress creates a file named debug.log inside your wp-content folder and writes the error there. You open that file to read the full history of what went wrong.

Your log is more trustworthy than the screen. A user interface misses failures that never render there. But the PHP log file records everything, so check it first.

Where The debug.log File Lives

The default path is wp-content/debug.log. Reach it the same way you reached wp-config.php: over FTP, SFTP, SSH, or your host’s file manager. If the file is not there yet, it usually means no error has fired since you enabled logging. Trigger the problem again and the file will appear.

One warning from real support cases. Some hosts hard-wire PHP’s error_log setting, so your errors may land in a system-level PHP log instead of wp-content/debug.log. If your log stays empty even though the site is clearly breaking, ask your host where PHP writes its error log.

Send The Log to a Custom Location

You do not have to keep the log in the default spot. Since WordPress 5.1 you can pass a file path to WP_DEBUG_LOG instead of true, and WordPress writes there:

define( 'WP_DEBUG_LOG', '/path/to/your/custom-debug.log' );

This helps in two ways. You can point the log to a folder outside your public web root. You can also route several dev sites to one shared file, so you watch one place. If your own code checks the constant, note the change. A strict test like true === WP_DEBUG_LOG returns false once you set a path. Use false !== WP_DEBUG_LOG instead.

How to Enable Debug Mode without Editing wp-config.php

You can turn on WordPress debugging without touching code at all. Many managed hosts include a debug toggle in their dashboard, and free plugins can flip the same constants for you. Both options suit site owners who would rather not open an FTP client or risk a typo in a core file.

Host dashboard toggles

Managed WordPress hosts often build debug mode into their control panel. Providers like Kinsta, DreamHost, and Raidboxes let you switch debug mode on with one click. Some show the log right in the dashboard too. On a few of these hosts wp-config.php is read-only for security, so the dashboard toggle is the intended path. Use a staging environment when the host offers one, since enabling debug mode on a live box can briefly expose PHP details to visitors.

A debug plugin

A plugin is the no-code route when your host has no toggle. Search the WordPress plugin directory for “debug” and you will find several. Popular options set WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY for you and add a settings screen to manage them. Install, activate, debug, then deactivate when you finish.

One honest caveat. Standard plugins load after must-use plugins and after core, so they can miss the earliest errors and some strict-standards notices. For catching every error, the wp-config.php method plus the raw debug.log stays the most complete. Use a plugin for convenience, not as your only safety net.

How to Read the WordPress Debug Log

Reading the debug log means matching each entry to the file and line that caused it. A typical line names the error type, the message, and the exact file and line number. That location is your starting point, because it points straight at the plugin, theme, or snippet that failed.

Take a common example. A call to an undefined function in a theme’s footer.php produces a fatal error naming that file and the line. You open footer.php, jump to the line, and there is your culprit. The message tells you what PHP could not do, and the path tells you where to fix it.

Log entries fall into a few buckets. Fatal errors stop the page from loading and need a fix now. Warnings point to real problems that may not break the page yet. Notices and deprecation messages flag code that works today but will age out with a future PHP version. All of them are worth reading, because today’s notice is often next year’s fatal error.

Not every failure lands in this file, though. A client-side problem like a 431 request header too large error comes from the browser and server headers, not your PHP, so debug.log stays quiet on it. When the page breaks but the log is empty, the cause often sits outside WordPress.

Expect noise. WP_DEBUG reports everything, so an active site with many plugins can fill the log with warnings and notices from third-party code. Chasing your own bug? Some developers prefix their log messages with a tag. Then they run a command like tail -f debug.log | grep YOURTAG to watch only their own output. On macOS, the Console app can open the log and filter it in real time. That turns a wall of text into something you can scan.

Other WordPress Debugging Tools Worth Knowing

Beyond the three core constants, WordPress ships a few more debugging switches, and the plugin directory adds stronger tools. Reach for these when the standard log does not explain the problem, especially for slow pages, script issues, or heavy database load.

SCRIPT_DEBUG

SCRIPT_DEBUG forces WordPress to load the full, un-minified versions of its core CSS and JavaScript files instead of the compressed ones. The default is false. Set it to true when you are testing changes to built-in .js or .css files and need readable source to work with.

define( 'SCRIPT_DEBUG', true );

SAVEQUERIES

SAVEQUERIES records every database query into an array you can inspect, along with how long each query took and which function called it. It is the tool to reach for when a page feels slow and you suspect a plugin is hammering the database.

define( 'SAVEQUERIES', true );

This one carries a cost. Saving every query slows the site, so run it on a staging copy when you can and turn it off the moment you finish.

Query Monitor

The Query Monitor plugin is a free developer tool. It reports database queries, PHP errors, hooks, and HTTP calls from the admin toolbar. It also captures AJAX and REST API errors, which are easy to miss. Install it, activate it, and a new panel gives you a live breakdown of what each page is doing. It is one of the most useful debugging plugins in the directory.

Server logs

Your server keeps its own logs, separate from WordPress. When a problem does not show in debug.log, check the server error log. It catches failures that happen before PHP even hands off to WordPress. Managed hosts usually expose these logs in the dashboard. On other hosts, check your host’s documentation for the path.

Server-side status errors surface here rather than in debug.log. A 503 service unavailable error, a 522 connection timeout, or a 521 web server down error usually traces back to the server or your CDN. The server log is where those show up, so start there when WordPress itself looks fine.

How to Keep Debug Logging Safe and Fast on a Live Site

Debug logging is safe on production when you hide errors from visitors and manage the log file. Keep WP_DEBUG_DISPLAY set to false so nothing leaks on the page. Store the log where the public cannot reach it. Clear or rotate the file so it does not balloon.

Two risks come up most. The first is exposure. An error printed on a live page can reveal file paths, function names, or a username. Each one hands an attacker a small clue. Logging with display off removes that risk while keeping the data you need. The second is file size. The log grows with every warning and notice, and on a busy site it can reach many megabytes. A giant log is slow to open and eats disk space. Download it for reference, then delete it. WordPress starts a fresh file on the next error.

Performance is a real but small concern. The overhead of logging is minor, and good caching keeps PHP from running on every request, which shrinks the impact further. Some hosts rotate the debug log daily and compress old copies. That keeps the file manageable on production, without losing recent history. When you finish troubleshooting, set the constants back to false or remove the snippet, because there is no reason to log forever.

Turn Debugging into a Habit

Debugging is one job. Answering the customers who hit the bug is another. That second job piles up while you are head-down in a log file. A tester reports the white screen. Three customers open tickets about the same broken checkout. Now your support queue competes with your debug.log for attention.

This is where a WordPress-native helpdesk earns its place. Fluent Support runs inside WordPress, so the tickets from a broken release land in the same admin where you are already working. Its workflow automation can route and tag the incoming reports on its own. Its AI features can summarize a thread or draft a first reply. Agents stop typing the same status update over and over. Set that up once through the feature set, and the queue keeps moving while you fix the actual bug. Starting from scratch, the same admin walks you through how to set up a support ticket system in WordPress in a few steps.

The point is simple. Debug mode tells you what broke. A support system that clears the busywork gives your team the hours to go read the log and fix it, instead of drowning in duplicate tickets first.

Wrapping Up

You now know how to debug a WordPress site from the switch to the fix. WP_DEBUG turns the reporting on. WP_DEBUG_LOG saves it. WP_DEBUG_DISPLAY keeps it out of your visitors’ sight. The log at wp-content/debug.log names the file and line behind each error. Tools like Query Monitor and SAVEQUERIES dig deeper when you need more.

Your next move is small. Back up your site, add the safe three-line snippet to wp-config.php, reproduce the bug, and open the log. Read the top error, go to the file and line it names, and fix that one thing. Then set the constants back to false when you are done.

And when a broken release fills your inbox faster than you can read the log, let a WordPress-native helpdesk carry the tickets. See how Fluent Support keeps your support queue moving so your team can focus on the debugging that actually clears the problem.