Plugins Plugin hub Backup SEO Caching Security Forms WooCommerce Images Best backup plugins
Hosting Hosting directory Shared Managed Cloud India
Themes & builders Compare Rank Math vs Yoast
Tools All tools Hosting finder Plugin stack builder Cost calculator Salt generator Theme detector Who is hosting this? Speed test Headline analyzer robots.txt generator Redirect generator Uptime calculator Blog name generator
Best lists Best backup plugins Deals
Guides All guides Speed up WordPress Choose hosting Back up WordPress
How we test

Troubleshooting · Guide

How to Turn On WordPress Debug Mode (WP_DEBUG) Safely

Short answer

Add define( 'WP_DEBUG', true ), define( 'WP_DEBUG_LOG', true ) and define( 'WP_DEBUG_DISPLAY', false ) to wp-config.php above the stop-editing line. Repeat the fault, then read wp-content/debug.log for the file and line behind it. Turn debug mode off and delete the log when you finish.

Key takeaways

  • WP_DEBUG is false by default and is usually set to true on development copies of WordPress.
  • WP_DEBUG_LOG saves errors to wp-content/debug.log, while WP_DEBUG_DISPLAY set to false keeps them off the screen.
  • Add the debug lines above the stop-editing line in wp-config.php, never below it.
  • WordPress 5.2 added Recovery Mode, which shows a message instead of a white screen after a fatal error.
  • Delete debug.log and set WP_DEBUG to false when you finish, because the log can hold paths and server detail.

What is WordPress debug mode?

WordPress debug mode is a setting that makes PHP errors, warnings, and notices visible so you can find the cause of a fault.

It is controlled by the WP_DEBUG constant in wp-config.php. Developer.WordPress.org states that WP_DEBUG is false by default and is usually set to true on development copies of WordPress.

When you turn it on, WordPress raises error reporting to E_ALL. That change is shown on the wp-config page, which says setting WP_DEBUG to true raises the error reporting level to E_ALL.

Debug mode does not fix anything by itself. It shows the file, line, and message behind a blank page or a failed action, so you can act on real detail instead of guessing.

What do you need before you start?

You need a backup, file access, and a plan to turn debug mode off again after you finish.

Make a full backup of files and the database before you edit wp-config.php. The debugging handbook tells you to use a staging environment or take a backup before you change your site.

You also need a way to reach your files. Use your host file manager, SFTP, or SSH. The file sits in the root folder of your WordPress install, next to wp-admin and wp-content.

Keep a note of the exact lines you add. You will remove or set them to false later, and a short note makes that step simple.

  • A current backup you know how to restore
  • File access through your host panel, SFTP, or SSH
  • A plain text editor, not a word processor
  • 10 to 20 minutes, plus time to repeat the fault

How do you turn on debug mode safely?

Add three lines to wp-config.php above the stop-editing line, with display off and logging on.

Open wp-config.php in the root folder. Find the line that reads /* That's all, stop editing! Happy publishing. */.

Add the lines just above it, as shown in the debugging handbook.

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

WP_DEBUG turns debug mode on. WP_DEBUG_LOG writes messages to wp-content/debug.log. WP_DEBUG_DISPLAY set to false keeps errors off the screen for visitors.

Do not use 'true' in quotes. The debugging handbook warns that quoted 'false' is read as true because quotes make it a string, not a boolean value.

Save the file, then load the page that fails. WordPress will write new entries to the log file when the fault happens again.

What do WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY each do?

WP_DEBUG switches debug mode on, WP_DEBUG_LOG saves messages to a file, and WP_DEBUG_DISPLAY controls whether they show on screen.

The table below sums up the three constants from the debugging handbook.

ConstantSet toWhat it does
WP_DEBUGtrueTurns on debug mode
WP_DEBUG_LOGtrueSaves errors to debug.log
WP_DEBUG_DISPLAYfalseHides errors on screen
WP_DEBUG_DISPLAYtrueShows errors on screen
SCRIPT_DEBUGtrueLoads dev core files

WP_DEBUG_LOG needs WP_DEBUG set to true before it does anything. The same rule applies to WP_DEBUG_DISPLAY, as the debugging handbook states for both constants.

SCRIPT_DEBUG is a separate constant. It forces WordPress to load dev versions of core scripts and styles instead of the .min.css and .min.js files. Use it only when you are checking a change to a core script or style file.

SAVEQUERIES is another related constant. Setting it to true saves each database query with its time and calling function in the global $wpdb->queries array. The handbook warns that it has a performance cost, so turn it off when you stop debugging.

How do you read the debug log?

Open wp-content/debug.log in your file manager or SFTP client and read the newest entries at the end of the file.

Each entry gives a date, a time, and a message. A PHP fatal error names the file and line where the script stopped. A warning or notice names the code that ran just before the fault.

Work from the newest entry backward. The last fatal error is often the one that stopped the page. Earlier warnings can show the chain that led to it, such as a missing file or a call to a function that no longer exists.

If the log file does not exist after you repeat the fault, check two things. First, confirm that WP_DEBUG and WP_DEBUG_LOG are both true and placed above the stop-editing line. Second, check that the wp-content folder can be written to by the server.

Delete old entries before you repeat the fault if the file is large. That step leaves only fresh entries, which makes the cause easier to spot. Keep a copy first if the old entries may matter to your host or developer.

How do you use debug mode on a live site without showing errors?

Use logging only, keep display off, and work on staging first when you can.

The debugging handbook states that it is not recommended to use WP_DEBUG or the other debug tools on live sites, because they are meant for local and staging installs. If you must use them on a live site, logging is the safer choice.

With WP_DEBUG_DISPLAY set to false and @ini_set( 'display_errors', 0 ) in place, errors go to the log file instead of the page. Visitors see the normal page, while you still get the detail you need.

A staging copy is the best place for this work. It holds the same plugins, theme, and settings, but its errors do not reach visitors. Fix the fault there, then apply the same change to the live site.

Remember that the log file can hold paths, plugin names, and server detail. The wp-config page warns that error logs should not sit in a public folder, so delete the log when you finish.

What if errors still show on screen after you set display to false?

Check Recovery Mode, because WordPress 5.2 changed how fatal errors are shown on live sites.

WordPress 5.2 added Recovery Mode, which shows a message instead of a white screen when a plugin causes a fatal error. The wp-config page says white screens and PHP error messages are no longer shown to users in that case.

If you want errors shown on screen in a development install, you must disable the fatal error handler first. The wp-config page gives this pair of lines for WordPress 5.2 and later:

define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );
define( 'WP_DEBUG_DISPLAY', true );

Do not use that pair on a live site. It can show file paths and code detail to any visitor who loads a broken page. Use it only on a local or staging copy, and turn it off when you finish.

If the page still shows a white screen, the fault may sit outside WordPress. Check your host PHP error log next, and see the guide on the white screen of death for the wider checks.

How do you turn debug mode off again?

Set WP_DEBUG to false, set WP_DEBUG_LOG to false, and delete the log file.

Open wp-config.php again and change the lines to:

define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
define( 'WP_DEBUG_DISPLAY', false );

Save the file and load two or three pages on your site. The pages should load as normal, with no error text in the HTML. Then delete wp-content/debug.log from the server, or download it first if you need to keep it for a developer.

Leaving debug mode on can fill the disk with log entries. It can also show notices for code that still works, which may confuse later checks. Turning it off is part of the job, not an optional extra.

If you used a plugin to turn debug mode on, turn it off in the same place. Do not leave both the plugin setting and the wp-config.php lines active at once.

How long does it take, and how do you check it worked?

Allow 10 to 20 minutes, and check it worked by finding a fresh entry in the log after you repeat the fault.

The edit itself takes about 5 minutes. Reading the log and matching an entry to the fault takes the rest of the time. A fault that only happens on checkout or on a form submit will take longer, because you must repeat that exact action.

Check the result in three steps:

  1. Load the page that failed before the change.
  2. Open wp-content/debug.log and look for an entry with the current time.
  3. Match the file and line in that entry to a plugin, theme, or core file.

If no new entry appears, the fault may come from JavaScript, a server rule, or a cached page. Clear the cache, repeat the action in a private browser window, and check the log again.

When the log names a plugin, the next step is to find which plugin is at fault. The guide on the critical error screen covers the message WordPress shows when a fatal error stops a page.

What mistakes should you avoid?

Do not leave display on, do not edit below the stop-editing line, and do not skip the backup.

The most common mistake is setting WP_DEBUG_DISPLAY to true on a live site. Visitors then see file paths and error text, and search engines can store those pages. Keep display false on any site visitors can reach.

A second mistake is placing the lines after the stop-editing line. The debugging handbook states that you must insert them before that line, or WordPress may not read them as expected.

A third mistake is using quoted 'true' or 'false'. Those are strings, not boolean values, and WordPress reads a non-empty string as true. Write true and false with no quotes.

Other mistakes to avoid:

  • Editing wp-config.php with no backup copy saved first
  • Leaving SAVEQUERIES on after you finish, which slows the site
  • Sharing the full log file in a public forum post
  • Treating a notice as proof that a plugin is broken, when the page still works

Check your PHP version while you are here. WordPress.org recommends PHP 8.3 or greater, with MySQL 8.4 or MariaDB 10.11 or greater, and notes that WordPress also runs on PHP 7.4 and MySQL 5.5.5 in legacy installs. An old PHP version can cause deprecation notices that look like a plugin fault.

Frequently asked questions

Is it safe to turn on WordPress debug mode on a live site?

It is safer on staging, because the official handbook says debug tools are meant for local and staging installs. If you must use them live, keep display off and log to a file only, then turn debug mode off and delete the log as soon as you finish.

Where is the WordPress debug log file?

When WP_DEBUG_LOG is true, WordPress writes errors to wp-content/debug.log in your site files. Open it with your host file manager or SFTP client, read the newest entries at the end, and delete old entries first if the file is large.

Why does debug mode show warnings on pages that still work?

Debug mode raises error reporting to E_ALL, so it shows notices and warnings for code that runs but does not follow current rules. Those messages point to code worth fixing, but a warning alone does not prove that a plugin or theme is broken.

What does SCRIPT_DEBUG do in WordPress?

SCRIPT_DEBUG forces WordPress to load the development versions of core CSS and JavaScript files instead of the minified .min.css and .min.js files. Use it only when you are checking a change to a core script or style file.

How do I turn WordPress debug mode off?

Open wp-config.php, set WP_DEBUG and WP_DEBUG_LOG to false, save the file, and load a few pages to confirm they show no error text. Then delete wp-content/debug.log from the server, or download a copy first if a developer needs it.

Sources

  1. Debugging in WordPress WordPress Developer Resources
  2. Editing wp-config.php WordPress Developer Resources
  3. The built-in WordPress debugging options Learn WordPress
  4. Requirements WordPress.org
  5. Description of core php.ini directives PHP.net

Is your product missing, or something out of date?

Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.

About the editors

WPLegible editors

Researched from the primary sources listed above and checked against our editorial rules. About the site · How we test