Debugging in WordPress

WordPress hides PHP errors from visitors by default, which also hides the clue you need when something breaks. Debug mode can write those errors to a log file, and the browser console shows the JavaScript errors that break editors, page builders and sliders. Debugging tells you which plugin, theme or file the problem comes from, so you can update it, report it or replace it.

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. On some hosts it sits one folder higher, which WordPress also allows. 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, often 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 in that box.

With SFTP, connect with the details from your host in a client such as FileZilla or Cyberduck, download wp-config.php, keep a second copy as a backup, edit it in a plain text editor, and upload it back to the same folder. Use a plain text editor such as Notepad or TextEdit in plain text mode, never a word processor.

Some managed hosts don’t allow edits to wp-config.php and 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. If your file doesn’t have one, add the lines below above the line that reads /* That's all, stop editing! Happy publishing. */.
2. Replace it with these three lines:

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

3. 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. This is the safer 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 the server can’t write to the wp-content folder, which your host can fix. Open it in 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. This is usually the cause of a blank page or the “critical error” message.
• Warning: something went wrong but the page kept loading. Worth reporting, and sometimes the cause of missing content.
• Notice and Deprecated: code that works today but should be updated. These are rarely the cause of a visible problem.

The file may be open to anyone who knows its address, and Site Health warns that your site logs errors to a potentially public file. Delete the file when you finish. To keep the log out of public reach, give WP_DEBUG_LOG a file path in a folder outside public_html that the server can write to, instead of true:

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

Many hosts also keep their own PHP error log, which you’ll find in your hosting account. It’s useful when an error happens before WordPress loads.

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, the cause is often a JavaScript error. These 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 turn on 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, which usually names the plugin or theme.

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 request with a 403 or 500 status often points to a server security rule or a PHP error, which debug.log may explain.

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. WordPress emails the site’s admin email address a recovery mode link, which lets you log in with the faulty plugin or theme paused. If you can’t use the email, turn on debug mode as above, load the page again, and read the newest Fatal error line in debug.log; its file path usually 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 File Manager or your 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 settings, so the file stays tidy without them.

Ask an AI Assistant

An AI assistant such as Claude or ChatGPT can explain an error and suggest where to look. Use it together with the steps on this page, 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)