When a WordPress site breaks, the instinct is to start changing things. Deactivate a plugin, switch the theme, clear the cache, increase the memory limit, try something you read in a forum. Sometimes it works. Often it makes things worse, or fixes the symptom without revealing the cause, which means it comes back.
Good debugging is mostly about slowing down. Gather information first, form a hypothesis, test it in a controlled way and change one thing at a time. That process sounds boring, but it finds problems far faster than random clicking.
Here’s how I approach debugging WordPress, from the first step to the more advanced tools.
Start with what changed
Most problems appear after something changes. Before touching anything, ask:
- Was a plugin, theme or core update applied?
- Did someone install a new plugin or change settings?
- Was code deployed?
- Did the host change PHP versions or server settings?
- Did traffic suddenly increase?
If the problem started right after an update, that update is your prime suspect. An activity log plugin is invaluable here, because it records who changed what and when.
Turn on WordPress debugging properly
WordPress has built-in debugging controlled by constants in wp-config.php. The safest configuration logs errors to a file without displaying them to visitors:
Errors are written to wp-content/debug.log by default. You can set WP_DEBUG_LOG to a file path outside the web root instead, which is better on live sites, because debug.log in wp-content can sometimes be downloaded by anyone who requests it:
Never leave WP_DEBUG_DISPLAY on for a live site. It shows error messages, file paths and sometimes sensitive information to visitors.
There’s also SCRIPT_DEBUG, which makes WordPress load unminified versions of its own JavaScript and CSS. That’s useful when debugging editor or admin script problems.
Remember to turn debugging off when you’re done. Debug logs can grow very large, very quickly.
Read the error properly
Once you have an error message, read it carefully. PHP errors usually tell you exactly what went wrong and where:
This tells you:
- The type: a fatal error, which stops the page from loading.
- The problem: a function called get_field doesn’t exist.
- The location: line 24 of single.php in the theme.
In this case, the theme uses a function from a custom fields plugin that isn’t active. The fix is to activate the plugin, or better, make the theme check whether the function exists before calling it.
The file path is the most useful part. If it points to wp-content/plugins/some-plugin, that plugin is involved. If it points to the theme, look there. If it points to WordPress core, the real cause is often a plugin passing bad data into a core function, so look at the stack trace for the first non-core file.
Know the error levels
- Fatal errors stop execution and break pages.
- Warnings indicate something went wrong but execution continued.
- Notices and deprecations point to code that may break in the future.
Don’t ignore warnings and deprecations forever. They often become fatal errors after the next PHP upgrade.
Use recovery mode
Since WordPress 5.2, when a fatal error is caused by a plugin or theme, WordPress shows a message that the site is experiencing technical difficulties and emails the site administrator a special recovery link. Logging in through that link lets you access the dashboard with the problem plugin or theme paused, so you can deactivate it.
Make sure the administration email address in Settings, then General, is one you actually check. Recovery emails are useless if they go to an old address.
Check the server logs
Not every problem appears in debug.log. Server logs fill in the gaps:
- PHP error log: errors that happen before WordPress loads, or errors when WordPress logging isn’t enabled.
- Web server error log: problems like upstream timeouts, permission denials and configuration errors.
- Access log: what requests came in, their status codes and timing.
A 502 or 504 error usually leaves clues in the web server error log, like “upstream timed out” or “connect() failed”, pointing to PHP-FPM problems. A 403 might be a security rule or file permission issue.
On managed hosting, you’ll find logs in the control panel. On your own server, they’re usually under /var/log.
Isolate the cause
When you don’t know which component is responsible, isolate it systematically.
Plugin conflicts
The classic method is to deactivate all plugins and see whether the problem goes away. If it does, reactivate them one by one until it returns. On a live site, do this on a staging copy, or use a troubleshooting plugin that disables plugins only for your own logged-in session while visitors see the normal site.
With WP-CLI, you can test quickly without touching the database:
A faster approach for sites with many plugins is to split them in half. Deactivate half; if the problem disappears, it’s in that half. Keep halving until you find it.
Theme problems
Switch to a default theme on staging. If the problem disappears, it’s caused by the theme or an interaction between the theme and a plugin.
Caching
Some problems are actually stale caches: old CSS, outdated HTML or cached errors. Clear page cache, object cache, CDN cache and your browser cache, or test in a private window, before assuming code is broken.
Use Query Monitor
Query Monitor is a free plugin I install on staging, and sometimes temporarily on live sites, whenever I’m debugging. It adds a toolbar menu that shows, for the current page:
- PHP errors and warnings, with the component responsible.
- Every database query, how long it took and which plugin or theme ran it.
- Slow and duplicate queries.
- HTTP API calls to external services, with response times and errors.
- Hooks fired and which functions are attached.
- Scripts and styles loaded, and their dependencies.
- The template file used to render the page.
For performance debugging, it’s invaluable. Sorting queries by time often reveals a single plugin responsible for most of the database work. For functional bugs, the errors panel and hook information point you straight to the cause.
Debug the front end with browser tools
Not every bug is in PHP. If a button doesn’t work, a form won’t submit or a layout breaks, open your browser’s developer tools:
- Console: JavaScript errors, often caused by script conflicts or files failing to load.
- Network: failed requests, slow AJAX calls and REST API errors, with full request and response details.
- Elements: inspect HTML and CSS to see which styles apply and why.
A JavaScript error from one plugin can stop every other script on the page, which makes unrelated features break. The console tells you which file threw the first error.
For REST API and AJAX problems, the network tab shows the response body, which often contains a clear WordPress error code and message.
Step through code with Xdebug
For complex bugs in custom code, logging and guessing only go so far. Xdebug is a PHP extension that lets you pause execution at a line, inspect variables and step through code one line at a time, using an editor like VS Code or PhpStorm.
It’s best used in local development. Setting it up takes some effort, but for tricky logic bugs, it can save hours of adding and removing debug output.
Log your own debug information
Sometimes you just need to see what a variable contains at a particular point. Use error_log rather than printing to the page:
This writes to the PHP or WordPress debug log without affecting visitors. Remove these lines when you’re done, or wrap them in a check for WP_DEBUG.
Write down what you found
When you solve a problem, write down what happened, what caused it and how you fixed it. Over time, these notes become a personal knowledge base. The second time a similar problem appears, you’ll recognise it in minutes.
Frequently asked questions
Is it safe to enable WP_DEBUG on a live site?
Yes, if you log to a file and keep display off. Never display errors to visitors. Turn debugging off again when you’ve finished, and make sure the log file isn’t publicly accessible.
My site shows a white screen with no error. What now?
A blank page usually means a fatal error with error display turned off. Enable WP_DEBUG_LOG and check the log, or look at the server’s PHP error log. If you can’t reach the dashboard, use WP-CLI or rename the plugins folder over SFTP to disable all plugins temporarily.
How do I find which plugin is slowing my site down?
Query Monitor shows slow queries and which components caused them. The PHP-FPM slow log and profiling tools give deeper insight into time spent in PHP.
Should I debug on the live site?
Prefer a staging copy whenever possible. If a problem only happens on live, use read-only methods like logs and Query Monitor restricted to administrators, and avoid making experimental changes in front of visitors.
Final thoughts
Debugging WordPress well is less about knowing every error and more about following a calm process: find out what changed, turn on the right logs, read errors carefully, isolate components one at a time and use tools like Query Monitor and browser developer tools to see what’s really happening. Change one thing at a time, document what you learn, and problems that once took a day will take an hour.
