How to enable WordPress debug log

Enabling the WordPress debug log turns a vague white screen, broken admin action, or failed API request into a file-backed error trail that can be reviewed after the request finishes. That is often the fastest way to identify the exact plugin, theme file, or custom code path behind a problem that only appears under real site traffic.

The logging behavior is controlled from wp-config.php. WP_DEBUG enables WordPress debug mode, WP_DEBUG_LOG writes errors to wp-content/debug.log by default or to a custom path when one is defined, and WP_DEBUG_DISPLAY controls whether those warnings are also printed into the browser response. The log file is created only after a request actually triggers a notice, warning, or fatal error while debug logging is enabled.

Treat debug logging as a short troubleshooting window instead of a permanent production setting. Update existing debug constants in place rather than adding duplicate definitions, keep on-screen display disabled on public sites, and use a custom log path when policy requires the log file to live outside the publicly reachable web root.

1. Open a terminal session in the WordPress document root.

   $ cd /var/www/example.com/public_html

   Run the remaining relative commands from the directory that contains the live wp-config.php file. Some hosting layouts place that file one level above the web root or generate part of it from container or platform settings, so adjust the path when the active file lives elsewhere.

2. Check whether the site already defines any debug constants before editing the file.

   $ grep -nE "WP_DEBUG(_LOG|_DISPLAY)?|display_errors" wp-config.php

   No output means none of these settings are currently defined in that file.

   If one or more lines already exist, update those existing definitions instead of adding a second copy. Duplicate constants create noisy warnings and make it harder to tell which value is actually in effect.

3. Back up the current wp-config.php file before changing the debug policy.

   $ sudo cp wp-config.php wp-config.php.bak-$(date +%Y%m%d%H%M%S)

4. Edit wp-config.php and add or update the debug constants above the final stop editing line.

   $ sudo vi wp-config.php

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

   This combination keeps browser output clean while still writing the PHP warning, notice, or fatal-error details to the log file.

   WP_DEBUG_LOG can also be set to a full file path such as /var/log/wordpress/debug.log when wp-content is not writable or when the log should stay outside the public document tree.

5. Verify that the active file now contains the expected debug settings.

   $ grep -nE "WP_DEBUG(_LOG|_DISPLAY)?|display_errors" wp-config.php
   116:define( 'WP_DEBUG', true );
   120:define( 'WP_DEBUG_LOG', true );
   121:define( 'WP_DEBUG_DISPLAY', false );
   122:@ini_set( 'display_errors', 0 );

   WordPress reads these constants on the next request, so a web-server restart is normally unnecessary.

6. Trigger the failing page load, admin action, webhook, or API request again.

   The default wp-content/debug.log file usually appears only after the first logged event occurs, so it is normal for the file not to exist immediately after saving wp-config.php.

7. Read the newest log lines and identify the first plugin, theme, or custom file path that matches the failure.

   $ tail -n 50 wp-content/debug.log
   [29-Mar-2026 12:14:27 UTC] PHP Warning:  Undefined array key "settings" in /var/www/example.com/public_html/wp-content/plugins/example-plugin/example.php on line 81
   ##### snipped #####

   The most useful clue is usually the first path near the newest error, not the oldest line left in the file from an earlier troubleshooting session.

   If the failure occurs only in wp-admin after enabling a plugin or theme change, compare the log output with the recovery-mode email path.

   Related: How to use WordPress recovery mode

8. Restore the original debug policy after collecting the needed error details.

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

   If the site already had a custom debug configuration, restore the previous values or copy the backup back into place instead of forcing generic false values.

   Remove, rotate, or archive wp-content/debug.log after the investigation when it contains sensitive file paths, queries, or stack traces.