Debugging and critical errors
The Debug tab (key 3) is a live console for the site, like your browser's DevTools. WP Instances also watches every site for WordPress' "There has been a critical error on this website" and tells you what caused it.
The Debug tab has four sub-tabs: Console, Critical errors, Performance and Help. Its switches sit in the same bar.
The switches
| Switch | What it sets in wp-config.php |
Effect |
|---|---|---|
| Debug mode | WP_DEBUG and WP_DEBUG_LOG |
WordPress records errors, warnings and notices in wp-content/debug.log. |
| Show on page | WP_DEBUG_DISPLAY |
Also prints errors in the page itself. This can break layouts and AJAX responses. Only available while debug mode is on. |
| Unminified scripts | SCRIPT_DEBUG |
Loads the readable versions of WordPress' own JavaScript and CSS. |
The switches edit wp-config.php with WP-CLI, the same lines you would add by hand. The next page load already uses them. Turning debug mode off sets WP_DEBUG back to false; the log file is kept until you clear it.
All are off on a new site. PHP itself never prints errors into pages unless Show on page is on, as on real hosting.
Console
The console shows two sources together, newest at the bottom:
- WordPress log:
wp-content/debug.log, while debug mode is on. - PHP: PHP's own error log for this site. It also catches errors WordPress never sees, for example with debug mode off or in
wp-config.php.
What you can do:
- Filter by level (All, Errors, Warnings, Notices, Logs) and by source (All sources, WordPress log, PHP).
- Search… the messages.
- Identical messages are grouped, with a count such as ×12.
- Click a file name to open the file in VS Code at that line.
- Stack trace shows the trace under an entry.
- Pause stops following new entries; Follow resumes.
- Copy copies what's shown. Clear empties the log file.
The console keeps the last 1 MB of the log. The file itself can grow larger, so clear it now and then. The log file's path is shown at the bottom; click it to copy it.
While debug mode is off, the console says Debug mode is off and offers Turn on debug mode. PHP's own errors for the site still appear.
Error badge
While you browse a site, its Debug tab shows a red count of new errors and warnings. Opening the tab clears it.
Logging from your own code
error_log( 'checkout reached' );
error_log( print_r( $order, true ) ); // arrays and objects
error_log( wp_debug_backtrace_summary() ); // who called this
With debug mode on, the log can be read in the browser at
/wp-content/debug.log. That's fine on your PC. Never copy a site to a live server with debug mode on.
Critical errors
When a page shows "There has been a critical error on this website", PHP hit a fatal error. WP Instances records every fatal error, with or without debug mode, with:
- the error message, file and line
- the plugin, theme, must-use plugin or drop-in the file belongs to
- the page that hit it
- the PHP version it happened on
It even catches errors in wp-config.php, which WordPress' own handler can't. Errors are kept per site in wp-content/.wpx-errors.json.
Background check
WP Instances loads every site's homepage and /wp-admin/ every 3 minutes (sites with a job running are skipped). In the site list:
- error (red): the site shows a critical error right now.
- recent error (amber): a critical error happened in the last hour.
The banner
On every tab of a broken site, a banner names the cause, for example Caused by Plugin "WooCommerce" (woocommerce), the page, and how many times it happened. If PHP is too old for the site's WordPress, the banner says that instead. Its buttons:
| Button | What it does |
|---|---|
| Deactivate this plugin | Deactivates the plugin that caused the error. Its files are untouched. |
| Switch to a default theme | Activates the newest installed Twenty… theme. The broken theme stays installed. |
| Open in VS Code at line … | Opens the file at the line of the error. |
| Details | Opens the Debug tab. |
| Check again | Loads the site again now. |
| Dismiss | Hides the banner for a past error. |
Fixes never delete anything. Reactivate the plugin or theme after correcting it. After a fix, WP Instances checks the site again and tells you whether it works.
History
The Critical errors sub-tab lists every recorded error, with its full stack trace, how often it happened, the last time, the page and the PHP version. Clear history removes the list.
Performance
Performance lists recent page requests to the site with their duration, so slow pages, failing requests and heavy admin screens stand out. Static files such as images and CSS aren't listed.
- At the top: the number of Requests, the Median and Slowest duration, and Errors (5xx).
- Sort by Newest or Slowest.
- Hide background requests leaves out admin-ajax, heartbeat and wp-cron.
Over 1 second is slow for a local site. Over 3 seconds usually means a heavy plugin, an external API call or a slow database query.
Query Monitor
For each page's database queries, slow queries, hooks, HTTP API calls and memory, use Query Monitor. The Performance view can Install & activate it from wordpress.org, Activate it, or Deactivate it. Query Monitor then shows its panel in the admin bar while you browse the site logged in.
Good to know
- A white screen or "There has been a critical error": check Critical errors, or turn on debug mode and reload the page.
- If a site answers with an error but PHP recorded no fatal error, the banner suggests turning on debug mode and reloading the page.
- The Help sub-tab has this information inside the app.