The Ultimate WordPress Debugging Guide

Debugging WordPress doesn’t have to feel like chaos. When things break, slow down, or act strangely, there’s always a reason, and usually, a breadcrumb trail leading to it.

This guide is your roadmap for finding those breadcrumbs.

We’ll start with the easiest, safest steps anyone can follow, move into power-user techniques for people with server or command line access, and finish with developer-level tools for deep performance and code tracing.

By the end, you’ll not only know how to fix problems, you’ll understand them.

Start Here: Checking for Plugin or Theme Conflicts

Pre-flight Checklist

Before you begin:

• Confirm you have current backups (database and files).
• Record when the issue began and any relevant performance baselines (e.g., load times, error rate).
• Create a staging copy of your site and verify whether the issue appears there.
• If you have SSH or hosting-level metrics, monitor CPU, memory, and I/O usage while testing, spikes often confirm a deeper resource or plugin issue.

Thanks, Robin, for suggesting this pre-flight checklist!

Before making any changes, take a few minutes to observe what’s happening.

1. Open your browser’s developer console (Ctrl+Shift+I on Chrome) and look for red errors.
2. Check your PHP or web server error log for recent entries.
3. Note the exact time you see the issue, you can match that timestamp with log entries later.

This initial observation helps you form a hypothesis instead of guessing. Once you’ve captured what the system is telling you, then proceed with the standard plugin, theme, and cache isolation steps.

Before any debugging begins, always rule out plugin and theme conflicts. Many strange issues, from broken layouts to missing buttons or admin errors, can come from plugins not playing nicely together or a theme behaving unexpectedly.

Then, start to debug simple:

1. Switch to a default WordPress theme like Twenty Twenty-Five. This gives you a clean baseline and removes theme-specific code from the equation.
2. Test your plugins methodically.
   • Deactivate all plugins, then see if the issue disappears.
   • If it does, the problem is plugin-related.
   • Reactivate plugins in batches (for example, half at a time) until the issue returns. This “divide and conquer” method helps you find the culprit quickly.
3. Once you’ve identified the conflicting plugin or combination, keep them deactivated and proceed to the next steps in this guide to confirm the root cause.

Note: Switching themes directly in production can sometimes reset widgets, menus, and layout settings. If possible, use the Health Check & Troubleshooting plugin’s “Troubleshooting Mode” to safely test with a default theme without affecting what visitors see.

This should provide you with insight into whether this is related to one specific plugin or if two (or more) plugins are conflicting with each other.

If the conflict is so big that you’re just seeing a white screen when you visit your site in the browser, and you’re pretty sure it’s because of an update of a plugin, this is the best option. Get access to your site again:

• Log onto FTP and go to /wp-content/plugins/. You can disable plugins by renaming the plugin folder temporarily. This works for themes as well, btw.

Thank you, Pat, for mentioning this super obvious one in the comments 😅.

The Quick Checks

For site owners, editors, and curious beginners. No coding required.

1. Start with the Basics

Before diving into logs or code, begin with the simple stuff, the things that solve half of all WordPress weirdness.

Try these first:

• Clear your browser cache. Your browser may be showing an outdated version of your site. Try reloading with Ctrl + F5 (Windows) or Cmd + Shift + R (Mac).
• Clear your site cache. If you use caching plugins (like WP Rocket, NitroPack, W3 Total Cache, etc.), clear or purge all caches.
• Test in Incognito or a different browser. Sometimes browser extensions or cookies cause layout issues.
• Temporarily disable optimization plugins. Minifiers or lazy-loaders can break scripts or styles.
• Switch to a default theme. Go to Appearance → Themes and activate “Twenty Twenty-Five.” If the problem disappears, your theme is the cause.

Bonus: Install the free Health Check & Troubleshooting plugin. It has a “Troubleshooting Mode” that temporarily deactivates plugins and switches themes only for you, so you can test safely without affecting site visitors.

2. Enable WordPress Debugging

WordPress has a built-in logging system that can show you what’s failing behind the scenes, typically PHP errors or warnings.

Here’s how to turn it on:

1. Open the wp-config.php file in the root of your site.
2. Add (or edit) these lines:

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

What this does:

• WP_DEBUG turns on error reporting.
• WP_DEBUG_LOG saves those errors to a file called debug.log.
• WP_DEBUG_DISPLAY hides them from your website visitors (so you don’t show sensitive info).

Now, visit your site again, the problem page, ideally. Then check the file:

/wp-content/debug.log

You’ll see lines like:

[06-Nov-2025 13:44:22 UTC] PHP Warning:  Undefined variable $price in /home/example/public_html/wp-content/themes/mytheme/functions.php on line 42

This tells you when it happened, what type of error it was, where it occurred, and in which file.

3. Use Your Browser’s Developer Tools

Every modern browser includes a “Developer Tools” panel, often called DevTools, that shows what’s happening on your website in real time.

To open it:

• Chrome: Ctrl + Shift + I (Windows) or Cmd + Option + I (Mac)

Tabs to know:

• Console: shows JavaScript errors (the red messages). For example, missing scripts or blocked requests.
• Network: shows requests made by your site (CSS, images, API calls). A red line means something failed, maybe a 404 or a 500 error.
• Performance: helps visualize what loads slowly.
• Lighthouse (Audit): runs a performance and accessibility report.

You don’t need to fix what you see yet; just note any red errors or failed requests. They’re valuable clues.

4. Check WordPress Site Health

Go to Tools → Site Health in your WordPress Dashboard.

• The Status tab shows warnings and recommendations (like outdated PHP or inactive plugins).
• The Info tab shows detailed environment data, your WordPress version, server software, PHP limits, active theme, and all plugins.

At the bottom, there’s a “Copy site info to clipboard” button.

If you’re asking for help, this is gold; it gives supporters or developers the context they need.

5. Document What You Find

Write down what you’ve done and what you’ve seen:

• What you changed before it broke
• What pages are affected
• Any errors from the Console or debug.log

You should now have:

• Debug logging turned on
• A copy of your system info
• A list of visible symptoms
• Initial clues about what’s failing

The System Detective

For site managers or advanced users with hosting or SSH access.

1. Read Your Server Logs

When WordPress reports “500 Internal Server Error” or goes blank, the famous White Screen of Death (WSOD), the server logs usually hold the truth.

Server logs are text files that record everything the server does, including PHP errors, crashes, and warnings.

Typical places to look (depends on your host):

• /var/log/apache2/error.log (Apache)
• /var/log/nginx/error.log (Nginx)
• Or inside your hosting panel (many have a “Logs” tab)

If you can’t find them or access them, reach out to your host’s support team. To watch the log live as it updates, use the tail command:

tail -f /path/to/error.log

“Tail” shows the tail end (the latest lines) of a file and updates in real time, so you can watch errors appear as you reload the site.

2. Understand Plugin and Theme Conflicts

Plugins and themes can conflict with each other, often when two try to modify the same part of WordPress.

The goal: isolate which one’s responsible.

Manual way:

• Deactivate all plugins.
• Switch to a default theme.
• Reactivate each plugin one at a time until the issue returns.

Faster way: use the WP-CLI.

3. What Is WP-CLI (and Why It’s Useful)

WP-CLI is the WordPress Command Line Interface, a tool that lets you control your site using commands in a terminal or SSH session.

For example:

wp plugin list

lists all plugins, while:

wp plugin deactivate --all

deactivates them all instantly.

Re-enable one plugin:

wp plugin activate plugin-name

It’s much faster for debugging than clicking around the Dashboard.

4. Use WP-CLI Diagnostic Tools

If you have WP-CLI installed, you can add official packages to diagnose your site deeper.

The WP Doctor allows you to check numerous items

wp doctor check

This runs built-in health checks, like missing constants, outdated PHP, or bad file permissions.

WP Profile

wp profile stage

This measures how long each stage of a page load takes (plugins, themes, core, etc.). It’s a great way to spot performance bottlenecks.

You may need to install both WP Doctor and WP Profile depending on your host’s setup. Contact your hosting company to make sure what you have and how you can have them added to your site.

5. Check Performance and Resource Limits

Sometimes problems are simply resource-related: not enough memory, too many database queries, or timeouts.

Increase PHP memory in wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );

Check database integrity:

wp db check

Transients are temporary bits of cached data WordPress stores in your database to speed things up.

If they pile up or expire incorrectly, they can cause slowdowns.

You can view them with:

wp transient list

and delete expired ones:

wp transient delete-expired

A wonderful plugin that allows you to manage your options in all the ways is the AAA Option Optimizer plugin.

6. Cron Jobs and Scheduled Tasks

WordPress uses “cron jobs”, automated tasks for things like publishing scheduled posts or checking for updates.

To see if one is stuck:

wp cron event list

If you see overdue jobs, you can run them manually:

wp cron event run --due-now

You’ll now know whether the issue lies in a plugin, theme, database, or server environment. If you can’t access the CLI, there is a plugin that allows you to see this as well: WP Crontrol

The Developer’s Lab

For developers and advanced troubleshooters who want to go beyond surface-level fixes.

1. Developer Plugins

Plugins like Query Monitor and Debug Bar are invaluable.

Query Monitor shows:

• Database queries (and how long they took)
• Hooks and actions firing on the page
• HTTP API calls (like API requests)
• Enqueued scripts and styles

Debug Bar adds a simple debug menu in the admin bar with errors, queries, and cache stats. More about how I diagnose WordPress performance bottlenecks.

Install via Dashboard or WP-CLI:

wp plugin install query-monitor --activate

2. Set Developer Constants

WordPress has extra constants for debugging at a deeper level.

Add to wp-config.php:

define( 'SAVEQUERIES', true );
define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );

What they do:

• SAVEQUERIES: Logs every database query and how long it took.
• SCRIPT_DEBUG: Forces WordPress to load unminified JS/CSS, useful for debugging scripts.
• WP_ENVIRONMENT_TYPE: Marks the site as development, staging, or production, useful for conditional code.

Remember to turn them off in production to avoid slowing down your site.

3. Tracing Code Execution

For full control, use a step debugger like Xdebug or Ray.

They let you pause code execution, inspect variables, and see function calls, like watching WordPress think in real time.

Local environments like LocalWP, Lando, or DevKinsta make this setup easier.

4. Debugging REST API and AJAX

Many modern WordPress features use the REST API or AJAX to fetch data behind the scenes.

You can inspect these in your browser’s Network tab:

• Look for requests to /wp-json/ (REST API) or admin-ajax.php.
• Click on them to see the response; an error message often explains the issue directly.

For deeper testing, use Postman or curl:

curl https://example.com/wp-json/wp/v2/posts

5. Profiling Performance

To find what’s slow:

• Use wp profile, a WP-CLI command to see which stages are heavy.
• Query Monitor shows which plugin, query, or hook consumes time.

Combine both to track slowdowns to exact code lines.

6. Collect and Share Environment Data

When you’ve gathered your findings and need to share them (for example, with your host or support team), use WP-CLI to summarize:

wp --info
wp core version
wp plugin list
wp theme list

These commands reveal your WordPress version, PHP version, and active components, without exposing passwords or sensitive data.

Appendix: Tools and References

Category	Tool / Resource	Description
WordPress Docs	Debugging in WordPress	Official reference for constants and logging
Health & Info	Health Check Plugin	Troubleshooting mode and system info
Developer Tools	Query Monitor, Debug Bar	Detailed debugging data
Command Line	WP-CLI	Manage WordPress via terminal
Performance	wp-cli/profile, DevTools Performance Tab	Find slow hooks, queries, and scripts

FAQs

What is the White Screen of Death (WSOD)?

The White Screen of Death occurs when WordPress fails to load due to a serious PHP error, leaving you with a blank page. It typically happens when a plugin or theme triggers a fatal error. The best way to diagnose it is to enable WP_DEBUG_LOG in wp-config.php and check the debug.log or your server’s error log. You can also rename the plugins folder temporarily to disable all plugins and confirm if one is responsible.

What is a PHP fatal error vs. a PHP Notice?

A PHP fatal error stops WordPress from running. It means the code encountered a problem so serious it couldn’t continue, for example, calling a function that doesn’t exist. These errors appear as Fatal error: in your logs.

A PHP Notice, on the other hand, doesn’t stop execution. It simply warns that something may be off, like using a variable that hasn’t been defined. Notices can safely be ignored in most cases but are worth reviewing if they appear frequently.

What Does PHP Deprecated Mean?

A deprecated warning means a function or feature is outdated and will be removed in future versions of PHP or WordPress. It still works now but should be updated. These are usually marked as Deprecated: in your logs. Plugin and theme developers should address these warnings, but they rarely cause immediate failures.

Why Does My Site Go Blank After an Update?

If your site goes blank immediately after updating a plugin, theme, or WordPress core, it’s often due to incompatible code or PHP version differences. Roll back the update (if possible) or disable the conflicting plugin via FTP or WP-CLI. Always test updates in a staging environment first to avoid downtime.

What If Debug Logs Don’t Appear?

If debug.log isn’t being created, check that your wp-content folder is writable by the server. You can also add this to wp-config.php to specify an explicit log location:

define( 'WP_DEBUG_LOG', '/path/to/your/logs/debug.log' );

Also make sure WP_DEBUG is set to true and that your server’s PHP settings allow error logging.

Why Are There So Many Warnings in My Log?

Some plugins are verbose in their error reporting, even for minor issues. Frequent notices or deprecated warnings often indicate outdated or sloppy code, not necessarily a critical error. Focus first on warnings and fatal errors, then review notices later if you want to clean up your codebase.

Wrapping Up

Debugging WordPress isn’t just about fixing what’s broken; it’s about understanding how your site works.

Next time something feels off, don’t panic. Open your logs, your tools, and your curiosity. WordPress is telling you what’s wrong; you just have to learn to listen.