How to Debug WordPress: Enable WP_DEBUG & Read Error Logs

When a WordPress site shows a blank white screen, a cryptic error message, or just stops working, the fastest way to find the cause is to turn on WordPress debugging and read the error logs it produces. This guide walks you through enabling WP_DEBUG (and its companion constants) and then locating and interpreting the log file so you can fix the underlying issue with confidence.

What You’ll Need

• Access to your WordPress site’s files via an FTP client (like FileZilla) or your hosting provider’s file manager.
• A text editor (Notepad++, Sublime Text, or even plain Notepad) to edit the wp-config.php file.
• Basic understanding of how to navigate folders on your server.
• If your site is on a managed host (like WP Engine or Kinsta), you may need to use their own debugging tools instead—check their documentation first.

Step-by-Step

1. Back up your wp-config.php file. Before editing any core file, download a copy to your computer. This file controls critical settings, and a mistake can take your site down.
2. Locate wp-config.php. Connect to your server via FTP or open the file manager in your hosting control panel. The file is in the root folder of your WordPress installation (usually named public_html, www, or your domain name).
3. Open wp-config.php in a text editor. Look for the line that says define( 'WP_DEBUG', false );—it’s usually near the bottom. If you can’t find it, don’t worry; you’ll add it yourself.
4. Enable WP_DEBUG. Change the line to define( 'WP_DEBUG', true );. If the line doesn’t exist, add it just before the line that says /* That's all, stop editing! Happy publishing. */.
5. Enable the log file. Add the following two lines right after the WP_DEBUG line:
   define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
   The first creates a debug.log file in your wp-content folder. The second hides errors from visitors (so your site doesn’t show raw PHP warnings to the public) while still writing them to the log.
6. Save and upload wp-config.php. Save the file locally, then upload it back to your server, overwriting the original.
7. Reproduce the error. Visit the page or perform the action that was causing the problem. This will trigger the error and write details to the log file.
8. Open the debug.log file. Navigate to your wp-content folder. You should see a file named debug.log. Download it and open it in your text editor.
9. Read the log. Each entry typically looks like:
   [12-Jan-2025 14:32:05 UTC] PHP Warning: Undefined array key "foo" in /path/to/theme/functions.php on line 42
   Look for the file path and line number—that’s where the problem is. The most common entries are PHP Warning, PHP Notice, and PHP Fatal error. Fatal errors are the most serious.
10. Fix the issue. Open the file mentioned in the log, go to the line number, and correct the code. If you’re not comfortable with PHP, share the exact log entry with your developer or hosting support.
11. Disable debugging once fixed. After resolving the issue, set WP_DEBUG back to false and remove the WP_DEBUG_LOG and WP_DEBUG_DISPLAY lines (or set them to false). Leaving debugging on can slow your site and expose sensitive paths.

Common Mistakes

• Editing the wrong wp-config.php. Some hosts have multiple WordPress installations. Make sure you’re editing the one for the site you’re debugging.
• Forgetting to set WP_DEBUG_DISPLAY to false. If you leave it true, visitors might see error messages that reveal server paths and database details.
• Not reproducing the error. If you enable debugging but don’t visit the broken page, the log will stay empty.
• Deleting the log file too early. The log accumulates errors over time. If you delete it before reproducing the issue, you lose the evidence.
• Editing wp-config.php with a word processor. Word processors add invisible formatting characters that break PHP. Use a plain text editor.

Tips

• Use a staging site. If possible, test changes on a staging copy first to avoid affecting live visitors.
• Check the log after every change. After fixing a line, reload the page, then check the log again to see if new errors appear.
• Search for the exact error message. Copy the full message into a search engine—chances are someone else has solved it.
• Enable the WordPress debug bar. For advanced debugging, install the Query Monitor plugin to see database queries, hooks, and PHP errors in the admin bar.
• Keep a copy of the original wp-config.php. If you mess up, you can restore it quickly.

Troubleshooting

• No debug.log file appears. Make sure you added the constants correctly and that the wp-content folder is writable by the server. Check the folder permissions—it should be 755 or 775. If you’re on a managed host, they may block file creation; use their own error log viewer instead.
• The site goes blank after editing wp-config.php. You likely have a syntax error. Download the file and check for missing semicolons or quotes. Restore your backup if needed.
• Errors still appear on the front end. Your theme or a plugin may be setting its own display settings. Add ini_set('display_errors', 0); to wp-config.php temporarily, or check if your host has a separate error reporting setting.
• The log file is huge. It accumulates all errors, including minor notices. Delete it after fixing major issues, and consider setting WP_DEBUG_DISPLAY to false to avoid bloat.
• You can’t access the server files. Some shared hosts restrict FTP access. Use the file manager in your hosting panel, or contact support to enable debugging for you.

Frequently Asked Questions

What is the difference between WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY?

WP_DEBUG turns on PHP error reporting. WP_DEBUG_LOG writes those errors to a debug.log file. WP_DEBUG_DISPLAY controls whether errors are shown on the screen. For a live site, you typically set WP_DEBUG true and WP_DEBUG_LOG true, while WP_DEBUG_DISPLAY false hides errors from visitors.

Where is the debug.log file located?

It’s in the wp-content folder of your WordPress installation. The full path is usually /public_html/wp-content/debug.log.

Do I need to delete debug.log after fixing errors?

Yes, it’s a good practice. The file can grow large and slow down your site if left unchecked. Deleting it after a fix ensures you start fresh and only see new errors.

Can I enable WP_DEBUG without editing files?

On some managed hosts, you can enable debugging from the control panel (e.g., WP Engine’s Debug mode). Otherwise, you must edit wp-config.php. Some plugins like WP Debugging can also do it for you, but they still modify the same file.

Why do I see errors even when WP_DEBUG is false?

Your hosting provider may have its own error reporting enabled, or a plugin/theme might override the setting. Check your server’s PHP error log (often in the hosting control panel) and ensure no plugin sets ini_set('display_errors', 1).

Is it safe to leave WP_DEBUG true permanently?

No. It can expose file paths and database info to visitors if WP_DEBUG_DISPLAY is true, and it consumes server resources. Turn it off once you’ve resolved the issue.

Related

• Deezer AI Music Filtering: What It Blocks and What It Doesn’t
• Full-Page Webpage Screenshots and PDFs: A Developer Guide
• When Upgrading Blu-ray to 4K Is Worth It