Debugging in WordPress

WordPress hides PHP errors from visitors, and that also hides the clue you need when part of your site breaks. Debug mode writes those errors to a log file, and your browser’s console shows the JavaScript errors that stop editors, page builders and sliders from working. Either one tells you which plugin or theme the problem comes from, so you know what to update, report or replace.

Open wp-config.php

Debug mode is set in wp-config.php, the configuration file in the folder WordPress is installed in, next to the wp-admin and wp-content folders. If it isn’t there, look one folder up; WordPress allows that location too. The file holds your database password and security keys, so edit it carefully and never share its contents. Here’s how to open it in your Hosting File Manager.

1. Log in to your hosting account and open the File Manager.
2. Open the folder WordPress is installed in, such as public_html.
3. Right-click wp-config.php and choose Download to keep a backup copy on your computer.
4. Right-click wp-config.php again and choose Edit. If the File Manager asks about the file’s encoding, click Edit again.

If you use SFTP instead:

1. Connect with the details from your host in a client such as FileZilla or Cyberduck.
2. Download wp-config.php and keep a second copy as a backup.
3. Edit it in a plain text editor, such as Notepad or TextEdit in plain text mode. A word processor adds formatting that breaks the file.
4. Upload it back to the same folder.

Managed hosts that lock wp-config.php offer a debug switch in their own dashboard instead. If you can’t find the file or can’t save it, ask your host.

Turn On Debug Mode

Every wp-config.php file made from the WordPress sample already contains this line, near the bottom:

define( 'WP_DEBUG', false );

Change that line rather than adding a second one. PHP keeps the first definition of a constant, so a second WP_DEBUG line further down is ignored and debugging stays off.

1. Find the WP_DEBUG line and replace it with these three lines. If your file has no WP_DEBUG line, add them above the line that reads /* That's all, stop editing! Happy publishing. */.

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

2. Click Save Changes.

WP_DEBUG turns debug mode on, WP_DEBUG_LOG writes every error to a log file, and WP_DEBUG_DISPLAY set to false keeps the errors off the screen. Logging without displaying errors is the safe setup for a live site. Setting WP_DEBUG_DISPLAY to true prints errors on the page for everyone, visitors included, so use it only on a local or staging site.

Read debug.log

With logging on, reproduce the problem: load the broken page or repeat the action that fails. WordPress then writes the errors to wp-content/debug.log. PHP creates the file when it logs the first error. If it isn’t there, either no PHP error has happened yet, or WordPress can’t write to the wp-content folder and your host needs to fix the folder’s permissions. Open the log in your Hosting File Manager with View or Edit, or download it.

Each line starts with the date and time, then the type of error, the message, and the file and line it came from:

[02-Oct-2026 14:05:11 UTC] PHP Warning:  Undefined variable $title in /home/northfield/public_html/wp-content/plugins/example-plugin/includes/class-example.php on line 42

The folder after wp-content/plugins/ or wp-content/themes/ names the plugin or theme. Look at the newest lines first, and at the lines with the same time as your test. The error types are:

• Fatal error and Parse error: PHP stopped. A fatal error is what causes a blank page or the “critical error” message.
• Warning: something went wrong, but the page kept loading. Report it, and check it first when content is missing from the page.
• Notice and Deprecated: code that still works but should be updated. These don’t stop a page from loading.

Unless your host blocks it, anyone who knows the address of debug.log can open it, and Site Health warns that your site logs errors to a potentially public file. Delete the file when you finish. To keep the log private, give WP_DEBUG_LOG a file path in a folder outside public_html that WordPress can write to, instead of true:

define( 'WP_DEBUG_LOG', '/home/northfield/logs/wp-debug.log' );

If your host keeps its own PHP error log, you’ll find it in your hosting account. It records errors that happen before WordPress loads, which debug.log misses.

Find JavaScript Errors in the Browser Console

When a button does nothing, the Block Editor or Page Builder won’t load, or a slider stays blank, look for a JavaScript error. JavaScript errors don’t appear in debug.log; your browser shows them in its console.

1. Open the page with the problem.
2. Right-click the page and choose Inspect in Chrome, Edge or Firefox, then open the Console tab. In Safari, first enable Show features for web developers in Safari > Settings > Advanced, then choose Develop > Show JavaScript Console.
3. Reload the page and repeat the action that fails.
4. Errors show in red. Copy the error text and the file name on the right. When the error comes from a plugin or theme, the file name includes its folder.

WordPress loads compressed versions of its own scripts, which makes their errors hard to read. To load the readable versions while you test, add define( 'SCRIPT_DEBUG', true ); to wp-config.php next to the debug lines, and remove it when you finish. The Network tab next to Console shows failed requests. A 403 status points to a security rule, which Fixing Saves Blocked by a Firewall covers, and a 500 status points to a PHP error that debug.log records.

Check Site Health

ToolsSite Health runs checks on your site and lists its setup. The Status tab shows problems WordPress has found, such as an outdated PHP version or a failed loopback request, and it warns you while debug mode is on. The Info tab lists your WordPress, PHP, theme and plugin versions, and the WordPress Constants section shows the current values of WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY, so you can confirm your change took effect. Click Copy site info to clipboard to paste the whole list into a support request; it leaves out your database details.

There Has Been a Critical Error on This Website

This message means PHP hit a fatal error. When the error happens in the dashboard or on the login page, WordPress also sends a recovery link to your site’s admin email address. If you don’t get the email, turn on debug mode as above, load the page again, and read the newest Fatal error line in debug.log; the folder in its file path names the plugin or theme. Identifying Plugin Issues covers recovery mode and how to deactivate a plugin when you can’t log in.

Turn Debug Mode Off

When you’ve found the cause, set debugging back to its default so the log doesn’t keep growing.

1. Open wp-config.php in your Hosting File Manager or SFTP client.
2. Change the WP_DEBUG line back to:

   define( 'WP_DEBUG', false );

3. Delete the WP_DEBUG_LOG and WP_DEBUG_DISPLAY lines, and the SCRIPT_DEBUG line if you added one.
4. Save the file.
5. Delete wp-content/debug.log.

With WP_DEBUG set to false, WordPress ignores the other two lines, but deleting them keeps the file clear for next time.

Ask an AI Assistant

Your AI assistant can explain an error and suggest where to look. Use it alongside these steps, and check its advice against your site before you change anything. Never paste wp-config.php, passwords, API or license keys, or personal data such as customer names and email addresses. Log lines can contain email addresses and server paths, so remove anything private before you paste them.

To read a debug.log excerpt:

These lines are from the debug.log file of a WordPress site. I have
removed private details. The problem I see: DESCRIBE WHAT HAPPENS AND WHERE.
PASTE THE LOG LINES HERE.
Explain in plain words what each error means, which plugin or theme
it comes from, and which one most likely causes my problem. Tell me
what to try first. Do not suggest editing core WordPress files or the
plugin's own files.

To read a browser console error:

This JavaScript error shows in my browser console on a WordPress
site when I DESCRIBE THE ACTION, ON WHICH PAGE.
PASTE THE ERROR TEXT AND FILE NAME HERE.
Which plugin or theme does it point to, is it likely the cause, and
how do I confirm that with a plugin conflict test?

To check your wp-config.php change without sharing the file, paste only the debug lines you added:

I added these lines to wp-config.php on a live WordPress site.
PASTE ONLY THE DEFINE LINES YOU ADDED.
Are they correct and safe for a live site, and what must I change
when I finish debugging?

Related

• Identifying Plugin Issues
• Fixing Page Not Found Errors
• Page Builder Troubleshooting
• Debugging in WordPress (WordPress.org)