Enabling the WordPress Debug Log (WordPress Debug Mode)

When you open your WordPress website to a blank page or a 500 error, WordPress is suppressing an error message that would identify the cause immediately. Enabling the WordPress debug log tells WordPress to write every PHP error, warning, and notice to a file — wp-content/debug.log — so you can see exactly which plugin, theme, or line of code is responsible.

TL;DR: Add these three constants to wp-config.php, directly above the /* That's all, stop editing! Happy publishing. */ line — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true );, and define( 'WP_DEBUG_DISPLAY', false );. After saving, reload the page and WordPress writes all PHP errors to wp-content/debug.log. Once you have finished troubleshooting, disable WordPress debug mode before pushing to live.

WordPress Debug Mode by Hosting Environment

How you access wp-config.php — and where debug.log ends up — depends on your hosting environment. Use the section that matches your setup.

Shared Hosting (cPanel / FTP)

On shared hosts such as Bluehost, SiteGround, or Hostinger, wp-config.php sits in your WordPress root directory, typically public_html/. Edit it using cPanel’s File Manager or an FTP client such as FileZilla.

Common permissions issue: if WordPress cannot write debug.log, the wp-content/ directory needs to be writable by the web server. The standard permission is 755 for directories. Do not set it to 777 on a shared host — that makes the directory world-writable and is a security risk.

From WP STAGING support tickets, shared hosting is where debug.log most often fails silently, because many shared hosts capture PHP errors in their own server-side log rather than letting WordPress create debug.log. If the file never appears after enabling WP_DEBUG, ask your host where their PHP error log is stored.

VPS / Managed Server (SSH)

With SSH access, edit wp-config.php directly from the command line:

nano /var/www/html/wp-config.php

After saving, tail the log in real time to watch errors as they happen:

tail -f /var/www/html/wp-content/debug.log

If debug.log is not created, check that the wp-content/ directory is owned by the web server user (www-data on Ubuntu/Debian, apache or nginx on CentOS/AlmaLinux):

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Local Development (LocalWP / DevKinsta / XAMPP)

debug.log appears in the same wp-content/debug.log location, but the base path depends on your local environment:

• LocalWP: ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta: ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP on Windows: C:xampphtdocs<site-name>wp-contentdebug.log

Local environments rarely have permissions issues because the web server and your user account run as the same process. If debug.log never appears, confirm your wp-config.php is in the WordPress root and not in a parent directory.

WP STAGING Staging Site

In our testing with WP STAGING, enabling debug mode on the staging clone is the safest approach — the clone is an exact copy of the live site, so any errors you reproduce will match the live environment without affecting real visitors.

To enable debug mode on your staging site, edit the wp-config.php inside the staging directory. WP STAGING creates the staging site as a separate subdirectory or subdomain with its own wp-config.php, so changes there do not affect the live site’s WP_DEBUG setting.

If you cannot log in to your staging website, the debug log is the first place to check — login failures on staging are most often PHP fatal errors that only appear in the log.

How to Activate WordPress Debug Mode

You can enable the WordPress "debug mode" by editing a few lines in the wp-config.php file of your WordPress installation:

1. Login to cPanel or log in to your site via FTP
2. Use the cPanel File Manager or your FTP client and edit the file wp-config.php
3. Copy the lines below to the file wp-config.php or if they already exist, change their values to true:

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

Attention: Make sure you copy the lines exactly as shown, and don’t forget a semicolon or other characters!

1. Paste the copied lines directly above the line that says
   /* That's all, stop editing! Happy publishing. */

After reloading the website, WordPress will write all PHP errors into the file debug.log.
WordPress saves that file into the folder: wp-content/debug.log

Display Errors on the WordPress Frontend

If you want to see the debug log errors directly on the screen instead of activating the debug.log file, change the line that says define( 'WP_DEBUG_DISPLAY', false );

Rename it to: define( 'WP_DEBUG_DISPLAY', true );.

WordPress Does not Create the debug.log Log File

Some hosting providers[1] do not allow the creation of the WordPress debug.log. They catch all PHP errors and let WordPress write them into a separate log file.

If WordPress cannot create debug.log, work through this decision tree to find the cause:

1. Look for an alternative log file. Check the site root for a file named error_log, or look for a /logs/ folder. Many shared hosts including HostGator redirect PHP errors to their own server-side log instead of allowing WordPress to write debug.log. If you don’t find any log files, ask your hosting provider where they store PHP error logs.

2. Check directory permissions. wp-content/ must be writable by the web server. On a server with SSH access, run:

ls -la /path/to/wp-content/

The directory should be owned by www-data (Ubuntu/Debian) or apache (CentOS). The standard permission is 755. If the directory is owned by root and the web server user cannot write to it, debug.log will silently fail to be created.

3. Check whether display_errors is overriding your settings. Some server php.ini configurations or .htaccess directives set php_flag display_errors Off, which can suppress output even when WP_DEBUG_DISPLAY is true. Check your hosting control panel’s PHP settings or ask your host.

4. Check whether a must-use plugin is suppressing errors. Files in wp-content/mu-plugins/ load before everything else and can override WordPress’s error handlers. If your host installed a must-use plugin that intercepts errors, it can prevent debug.log from being written. Inspect any files in wp-content/mu-plugins/ if that directory exists.

5. Check error_reporting level. If error_reporting is set too restrictively — for example, to E_ERROR only — PHP will not log warnings and notices. WordPress sets error_reporting(E_ALL) when WP_DEBUG is true, but a plugin or server configuration can change this after WordPress loads. See the PHP error_reporting documentation for the full list of constants and what each level covers.

6. Check that the log path directory exists. If you have already set WP_DEBUG_LOG to a custom path, confirm the directory at that path exists and is writable by the web server.

Alternatively, you can use the method mentioned above and change
define( 'WP_DEBUG_DISPLAY', false ); to
define( 'WP_DEBUG_DISPLAY', true );

If this works, you will see the relevant errors on the front end. That will help you to resolve the fatal error.

You can find more detailed instructions about enabling WordPress debug mode in the WordPress Debugging documentation.

At the time of writing this article: [1] HostGator

Alternate Method to Debug Fatal Errors When debug.log Isn’t Generated

Sometimes, when you enable WP_DEBUG mode to troubleshoot a fatal error, you might find that your hosting provider prevents the debug.log file from being created. Even setting WP_DEBUG_DISPLAY to true it doesn’t always help to show the error on the front end.

If you’re stuck in this situation, here’s a workaround that works when nothing else does.

Forcing Error Display in wp-config.php

This snippet forces the fatal error to be displayed:

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 Remember to remove the snippet after debugging and use only when you have FTP access for safe rollback.

Reading the WordPress Debug Log

Once debug.log exists, open it in any text editor. Each line follows this pattern:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Here is what each error class means and when to act on it:

PHP Fatal error — PHP stopped executing. This is always the cause of a blank page or 500 error. The file path and line number in the log entry show you exactly where to look. Find the plugin or theme whose file is named in the entry and deactivate it to confirm.

PHP Warning — PHP encountered something unexpected but kept running. Warnings do not cause blank pages on their own, but they often indicate a bug that will become a fatal error under different conditions. If you are enabling WordPress debug log to identify PHP warnings related to PHP configuration limits, a max_input_vars warning from a form-heavy plugin is a common entry.

PHP Notice — PHP noted a potential issue such as an undefined variable. Notices rarely indicate a real bug in production, but if the same notice appears thousands of times per page load it can signal a loop or recursion issue that degrades performance.

$wpdb database errors — Lines beginning with WordPress database error indicate a query failed. These usually point to a plugin generating a malformed SQL query or a problem in the WordPress database tables that the query targets. The error message includes the query that failed, which makes the offending plugin straightforward to identify.

When you find a fatal error or a repeated warning, look at the file path in the log entry. If it belongs to a plugin or theme, deactivate it, reload the page, and confirm that the log entries stop.

If the debug log surfaces REST API errors in WordPress, the log entry typically names the exact function that failed — follow the dedicated guide from that starting point. If it surfaces ERR_CONNECTION_REFUSED errors, those originate at the server or network layer rather than in PHP. For 414 Request-URI Too Large errors, the log usually identifies which plugin is generating the oversized URL.

Change the Location of the debug.log

You can change the path WordPress uses for error logging by changing the value of the constant WP_DEBUG_LOG.

Open wp-config.php and find the line that contains WP_DEBUG_LOG.

Search: define( 'WP_DEBUG_LOG', true );

Rename to: define( 'WP_DEBUG_LOG', '/logs/errors.log' );

That allows WordPress to write error messages to a different file path.

As a destination path you can also use /dev/stderr or /dev/stdout. That is useful in Docker or other containerised environments where you want all logs in a shared output stream.

Disable Debug Mode in WordPress After Troubleshooting

Once you have finished investigating, disable debug mode immediately. The debug.log file is accessible from the web by default at wp-content/debug.log, and it can contain database error details, file paths, and other server information that should not be publicly readable.

Delete the debug.log file and disable further error logging by changing define( 'WP_DEBUG', true ); back to define( 'WP_DEBUG', false );.

Always disable WordPress debug mode before pushing to live when working on a staging site. WP STAGING’s push workflow is the right checkpoint to confirm WP_DEBUG is off before the clone overwrites the live site.

Related Articles

• Blank White Page on a WordPress Staging Site
• How to fix an Error 500 and WordPress Blank White Page
• How to Debug JavaScript Errors in the Browser Console