How to enable debug mode on WordPress
WP_DEBUG reveals the exact file, line and message behind a "critical error on this website" or a blank screen. Set up correctly, it writes this information to a log without ever showing it to visitors.
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);Enabling debug mode without exposing the site
-
Access the site's files
wp-config.php sits at the root of the WordPress installation, at the same level as the wp-content, wp-admin and wp-includes folders. FTP, SFTP or access to the host's file manager is required.
-
Find the line to edit
Look for the line define('WP_DEBUG', false); If it doesn't exist, add the three constants just before the line /* That's all, stop editing! Happy publishing. */.
-
Separate display from logging
WP_DEBUG_DISPLAY set to false stops messages from appearing on public pages. WP_DEBUG_LOG set to true writes them to a file instead, which is the combination to use on a live site.
-
Reproduce the problem
Reload the page or action that triggers the error so WordPress logs the event.
-
Read wp-content/debug.log
This file lists PHP errors in chronological order, with the file, the line, and often the plugin or theme at fault.
-
Switch back to normal mode
Once the cause is identified, set WP_DEBUG and WP_DEBUG_LOG back to false, and delete the debug.log file if it holds sensitive information.
Why separate display from logging
WordPress's default configuration hides every error behind the generic message "There has been a critical error on this website", introduced since WordPress 5.2 to avoid exposing code to visitors. That's good protection, but it makes diagnosis impossible without file access.
Enabling WP_DEBUG alone is enough to make errors appear directly on the page, which is handy locally but dangerous in production: any visitor would then see the same messages, sometimes including file paths or internal function names. The combination of WP_DEBUG_LOG set to true and WP_DEBUG_DISPLAY set to false resolves that trade-off: errors keep being recorded, but only someone with access to the server's files can view them.
On a WooCommerce store, this setting is complemented by reading the plugin's own logs, accessible from WooCommerce, Status, Logs in the admin, which record payment, webhook and stock synchronisation errors separately.
Common mistakes
- Leaving WP_DEBUG_DISPLAY set to true on a live site: errors become visible to every visitor, including exploitable technical information.
- Forgetting that the debug.log file grows indefinitely once enabled: on a site generating a lot of PHP notices, it can reach several hundred megabytes within a few weeks.
- Looking for wp-content/debug.log when it doesn't exist yet: WordPress only creates it once a first error occurs after enabling debug mode.
- Editing wp-config.php without a prior backup: a syntax error in this file makes the entire site inaccessible, including wp-admin.
Frequently asked questions
Can debug mode make the critical error worse?
wp-config.php doesn't exist or I can't find it, what should I do?
The debugger shows several different errors, which one should I address first?
Should debug mode be enabled on a WordPress multisite install?
Is there a more complete tool than debug.log for diagnosing WordPress?
Describe your need in one minute
A few targeted questions so I can reply with an estimate rather than another questionnaire.