How to enable debug mode in WordPress?

To enable debug mode in WordPress, open your site's wp-config.php file and change define( 'WP_DEBUG', false ); to define( 'WP_DEBUG', true );. For a live site, also add WP_DEBUG_LOG set to true and WP_DEBUG_DISPLAY set to false, so errors are saved to wp-content/debug.log instead of being shown to visitors. Once you have found the problem, switch debugging off again.

Debug mode is the first tool to reach for when something breaks, whether it is a blank screen, a "critical error" message, or a plugin that silently stops working. In this guide you will learn what debug mode does, the different debugging constants, how to enable them manually, with WP-CLI, or with a plugin, how to read the log, and how to debug safely on a production site.

What Is WordPress Debug Mode?

WordPress debug mode is a built-in feature that makes PHP errors, warnings, and notices visible. Normally WordPress hides these messages to keep the site looking clean for visitors. That is great for production, but it means that when something fails, you often see nothing useful at all.

When debug mode is on, WordPress:

• Reports all PHP errors, warnings, notices, and deprecation messages.
• Shows notices about deprecated WordPress functions and arguments that plugins or themes still use.
• Optionally writes everything to a log file for later review.

These messages tell you which file and which line caused a problem, which usually points directly to the plugin or theme responsible.

Why Enable Debug Mode?

You will want debug mode when:

• Your site shows "There has been a critical error on this website."
• You see a blank white screen (often called the white screen of death).
• A plugin or theme feature stops working without any visible message.
• You are developing a plugin or theme and want to catch mistakes early.
• You need to check for deprecated code before a WordPress or PHP upgrade.

Understanding the Debugging Constants

WordPress controls debugging through a handful of constants defined in wp-config.php.

WP_DEBUG

define( 'WP_DEBUG', true );

This is the main switch. When true, WordPress sets PHP's error reporting to show all errors and enables WordPress's own deprecation notices. On its own, it displays errors directly on the page.

WP_DEBUG_LOG

define( 'WP_DEBUG_LOG', true );

When true, errors are written to wp-content/debug.log. You can also pass a custom file path:

define( 'WP_DEBUG_LOG', '/home/example/logs/wp-errors.log' );

Storing the log outside the public web folder is safer, because wp-content/debug.log can otherwise be downloaded by anyone who knows the URL.

WP_DEBUG_DISPLAY

define( 'WP_DEBUG_DISPLAY', false );

Controls whether errors are printed on screen. It defaults to true when WP_DEBUG is on. Set it to false on any site that real visitors can reach, and rely on the log instead.

SCRIPT_DEBUG

define( 'SCRIPT_DEBUG', true );

Loads the unminified "dev" versions of core JavaScript and CSS files. This is useful when you are debugging problems in the block editor, admin screens, or scripts that depend on core libraries.

SAVEQUERIES

define( 'SAVEQUERIES', true );

Saves every database query, how long it took, and which function called it, into the global $wpdb->queries array. Tools like Query Monitor display this data. It adds overhead, so use it only while investigating.

WP_DISABLE_FATAL_ERROR_HANDLER

define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );

WordPress normally catches fatal errors and shows the friendly "critical error" screen while emailing a recovery link to the admin. Developers sometimes disable this handler to see the raw error. Leave it alone unless you have a specific reason.

Method 1: Enable Debug Mode in wp-config.php

This is the standard method and works on every host.

1. Back up the file: Connect to your site with SFTP or your host's file manager and download a copy of wp-config.php.
2. Open the file: Edit it in a plain-text code editor, not a word processor.
3. Find the existing line: Look for define( 'WP_DEBUG', false );. It is usually near the bottom, above the "stop editing" comment.
4. Replace it: Swap that line for the block below.
5. Save and upload: Upload the file back to the server, replacing the original.

For a local or staging site, where only you can see the output:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'SCRIPT_DEBUG', true );

For a live site, where visitors must not see errors:

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

The @ini_set( 'display_errors', 0 ); line is a safeguard in case your server's PHP configuration overrides WordPress's setting.

Make sure these lines appear above this comment:

/* That's all, stop editing! Happy publishing. */

Also make sure WP_DEBUG is only defined once. If the original false line is still there, PHP will warn that the constant is already defined, and your new value may be ignored.

Method 2: Enable Debug Mode with WP-CLI

If you have SSH access and WP-CLI installed, you can change the constants without opening the file:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

The --raw flag writes true as a PHP boolean instead of the string 'true'.

To check the current values:

wp config get WP_DEBUG
wp config get WP_DEBUG_LOG

And to switch debugging off again:

wp config set WP_DEBUG false --raw
wp config delete WP_DEBUG_LOG
wp config delete WP_DEBUG_DISPLAY

Method 3: Use a Plugin

If you are not comfortable editing files, plugins can help.

• WP Debugging: A free plugin that sets the debugging constants in wp-config.php for you when activated and removes them when deactivated.
• Query Monitor: A free developer tools panel that shows PHP errors, database queries, hooks, HTTP API calls, and more for each page load, visible only to administrators.

Query Monitor does not replace WP_DEBUG, but it complements it well. Once activated, it adds a menu to the admin toolbar. If a page has PHP errors, the toolbar item turns red or orange, and clicking it shows exactly where the errors came from.

Keep in mind that a plugin cannot help if the site is so broken that WordPress will not load. In that case, use Method 1.

Method 4: Check Your Hosting Dashboard

Many managed WordPress hosts provide a debug toggle and error log viewer in their dashboard, so you can enable debugging with a click and read logs without SFTP. Look for options labeled "Debugging", "Logs", or "Developer tools" in your hosting panel. Hosts also keep server-level PHP error logs, which can contain errors that happen before WordPress even starts.

How to Find and Read the debug.log File

Once WP_DEBUG_LOG is enabled, reproduce the problem by visiting the broken page or repeating the action that fails. Then open:

wp-content/debug.log

With SSH access, you can watch the log in real time:

tail -f wp-content/debug.log

Or view just the last 50 lines:

tail -n 50 wp-content/debug.log

Understanding Common Error Types

Each line in the log starts with a timestamp, followed by the type of message.

PHP Fatal error: The code crashed and execution stopped. This is almost always the cause of a critical error or white screen.

[21-Sep-2026 10:15:42 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function get_field() in /var/www/html/wp-content/themes/mytheme/single.php:14

This example says a theme template calls get_field(), a function provided by Advanced Custom Fields, but the plugin is not active.

PHP Warning: Something went wrong, but execution continued. Warnings can cause features to break.

[21-Sep-2026 10:16:03 UTC] PHP Warning:  Undefined array key "title" in /var/www/html/wp-content/plugins/example-plugin/includes/render.php on line 38

PHP Notice: A minor issue, often harmless, but worth fixing in your own code.

PHP Deprecated: The code uses a function or feature that will be removed in a future version of PHP or WordPress. These are important before upgrading PHP.

[21-Sep-2026 10:17:11 UTC] PHP Deprecated:  Function wp_make_content_images_responsive is deprecated since version 5.5.0! Use wp_filter_content_tags() instead.

Tracing the Cause

Look at the file path in each message:

• A path inside wp-content/plugins/plugin-name/ points to that plugin.
• A path inside wp-content/themes/theme-name/ points to that theme.
• A path inside wp-includes/ or wp-admin/ usually means core received bad data from a plugin or theme. Look at the stack trace lines below the error to find which plugin or theme called the core function.

Once you know the culprit, you can update it, roll back to a previous version, deactivate it, or contact its developer with the exact error message.

Writing Your Own Messages to the Log

When debugging your own code, you can write values to debug.log with PHP's error_log() function:

function sajjad_debug_log( $data, $label = '' ) {
if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
return;
}

$message = is_scalar( $data ) ? (string) $data : print_r( $data, true );

if ( $label ) {
$message = $label . ': ' . $message;
}

error_log( $message );
}

Add this helper to a custom plugin or your child theme's functions.php, then use it anywhere:

function sajjad_log_saved_post( $post_id, $post ) {
sajjad_debug_log( $post->post_title, 'Saved post ' . $post_id );
}
add_action( 'save_post', 'sajjad_log_saved_post', 10, 2 );

Because the helper checks WP_DEBUG, nothing is logged once debugging is switched off. Still, remove temporary debugging calls when you are done.

Debugging When You Are Locked Out

If a fatal error prevents you from reaching the dashboard:

1. Check your email for recovery mode: WordPress usually emails the admin address a special link that opens the dashboard with the faulty plugin or theme paused.
2. Enable logging via SFTP: Use Method 1 to turn on WP_DEBUG_LOG, then reload the page and read the log.
3. Deactivate the culprit: Rename the plugin's folder in wp-content/plugins/ (for example, add -disabled to the name). WordPress will deactivate it automatically.
4. Use WP-CLI: Run wp plugin deactivate plugin-name --skip-plugins --skip-themes to disable it from the terminal.
5. Switch themes: If the theme is the problem, rename its folder so WordPress falls back to a default theme.

Debugging JavaScript Problems

PHP debugging does not catch JavaScript errors, which cause issues such as the block editor failing to load or buttons not responding.

1. Open the browser console: In Chrome, Edge, or Firefox, right-click the page, choose Inspect, and open the Console tab.
2. Reproduce the issue: Reload the page or repeat the action and look for red error messages.
3. Enable SCRIPT_DEBUG: Unminified core scripts give readable file names and line numbers.
4. Check the Network tab: Failed requests to /wp-json/ or admin-ajax.php often reveal server-side errors, and their responses may contain the PHP error message.

Best Practices for Debugging Safely

Never show errors to visitors: On live sites, always use WP_DEBUG_DISPLAY set to false. Displayed errors can reveal file paths and other details that help attackers.

Protect or relocate the log: Store the log outside the web root with a custom path, or block access to it. On Apache, add this to .htaccess:

<Files debug.log>
    Require all denied
</Files>

On Nginx:

location ~* /debug\.log$ {
    deny all;
}

Turn debugging off when finished: Set WP_DEBUG back to false and delete the old debug.log. Logs can grow large quickly on busy sites.

Use a staging site: Whenever possible, reproduce problems on a staging copy, where you can safely display errors and experiment.

Back up before changes: Take a backup before editing wp-config.php or deactivating plugins on a live site.

Fix, do not just hide: Notices and deprecation warnings often become real errors after a PHP or WordPress upgrade. Treat them as early warnings.

Switching Debug Mode Off

When you have fixed the problem, restore the production settings:

define( 'WP_DEBUG', false );

Remove the other debugging constants you added (WP_DEBUG_LOG, WP_DEBUG_DISPLAY, SCRIPT_DEBUG, SAVEQUERIES), delete wp-content/debug.log, and confirm the site still works normally.

---

FAQ: WordPress Debug Mode

---

Conclusion

Enabling debug mode is one of the most useful troubleshooting skills in WordPress. By setting WP_DEBUG and WP_DEBUG_LOG in wp-config.php, you turn vague symptoms like blank screens and critical errors into precise messages that point to the exact file and line causing the problem.

Use a staging site when you can, keep errors hidden from visitors on live sites, and pair debug.log with tools like Query Monitor and your browser console for a complete picture. Most importantly, switch debugging off and remove old logs once the issue is fixed. With that routine, you can diagnose most WordPress problems quickly and confidently.