Posted in

How to Debug WordPress

by WP95/
Debugging WordPress
Debugging WordPress

Debugging WordPress is one of those skills that transforms you from a site builder into a confident developer. Instead of guessing when something breaks, you’ll learn to observe, investigate, and fix problems with precision.

Whether it’s a blank screen, a slow page, a broken layout, or an error that mysteriously appears after an update — debugging tools give you the power to understand why things happen and what to do about it.

This guide is here to help you do just that.

What You’ll Learn

We’ll walk through the most useful debugging tools and techniques in the WordPress ecosystem, including:

  • Enabling and using WP_DEBUG and related constants
  • Finding and interpreting error logs
  • Using the powerful Query Monitor plugin to explore the inner workings of a page
  • Identifying conflicts between plugins, themes, or custom code
  • Using browser tools to catch frontend and JavaScript issues
  • Leveraging WP-CLI and performance tools when things get tricky

Who This Guide Is For

This guide is written for developers, tinkerers, freelancers, and even curious site owners who want to get better at troubleshooting their WordPress sites. No matter your skill level, you’ll find practical tips that help you save time and headaches.

You don’t need to be a full-time PHP expert or a Linux wizard — just a willingness to peek under the hood and explore.

Why Debugging Matters

Debugging isn’t just about fixing errors. It’s about gaining confidence in your codebase, learning how WordPress works behind the scenes, and delivering a more reliable experience for users and clients.

And perhaps most importantly: it makes you faster. What once took hours of head-scratching can become a 5-minute diagnosis with the right approach and tools.

Let’s dive in and start sharpening your WordPress debugging skills — starting with understanding the different types of errors you might encounter.

Understanding the WordPress Error Landscape

Before you dive into debugging tools, it’s essential to understand the types of problems you might run into when working with WordPress. Not every error looks like a flashing red alert — some are subtle, intermittent, or buried in logs.

Knowing how WordPress surfaces different kinds of issues will help you approach each problem with clarity and confidence.

Types of Errors You Might Encounter

  • PHP Errors: These include notices, warnings, and fatal errors. They often point to problems in theme or plugin code — such as calling an undefined function, using a deprecated feature, or referencing a missing file.
  • White Screen of Death (WSOD): A completely blank page often signals a fatal error that’s being hidden from view. This is one of the most frustrating issues because it provides no visual clues.
  • JavaScript Errors: Frontend scripts may fail silently or throw errors that only appear in the browser console. These can break interactivity, forms, menus, or AJAX-based features.
  • Database Errors: Missing tables, broken queries, or permission issues can cause critical failures or subtle bugs — like content not displaying as expected.
  • Performance Issues: These aren’t always “errors” in the traditional sense, but long page loads, slow admin panels, or resource-heavy plugins can signal deeper problems worth debugging.

Frontend vs Backend Errors

Some issues will only show up on the frontend (e.g. layout glitches, JavaScript failures), while others might break the admin dashboard or background processes like cron jobs or AJAX handlers. It’s important to test both sides of your site when troubleshooting.

Tip: If an issue disappears when you’re logged out, it’s often related to admin-only scripts, capabilities, or logged-in user checks.

Don’t Overlook the Subtle Signs

Not all bugs are dramatic. Some are sneaky:

  • A plugin silently fails to load
  • A widget shows up, but the data is stale
  • An AJAX request returns a 500 error that you never see without inspecting the network

These small hiccups are often early warning signs of deeper issues — and learning to spot them is a powerful debugging skill.

What Causes Most Errors in WordPress?

In practice, many issues come down to:

  • Plugin or theme conflicts
  • Outdated code (especially after core updates)
  • Server configuration limits or missing PHP extensions
  • Typos or logic bugs in custom code

With a basic understanding of what kinds of problems to look for, you’ll be better equipped to use the right tools for the job — starting with the most fundamental: WP_DEBUG.

🛠️ Using WP_DEBUG and Its Family of Constants

If you only learn one WordPress debugging tool, let it be WP_DEBUG. This powerful core feature lets you surface hidden PHP errors, log them for review, and gain insight into what’s going wrong behind the scenes.

Let’s break it down step by step.

🔧 Enabling WP_DEBUG

To activate WordPress debugging mode, open your wp-config.php file and look for this line:

define( 'WP_DEBUG', false );

Change it to:

define( 'WP_DEBUG', true );

This tells WordPress to start showing all PHP warnings, notices, and errors. If the line doesn’t exist, you can safely add it just before this line:

/* That's all, stop editing! Happy publishing. */

📝 Using WP_DEBUG_LOG

Want to log those errors instead of printing them on-screen? Add this:

define( 'WP_DEBUG_LOG', true );

This will create a file at wp-content/debug.log, where all PHP errors will be written. It’s super useful for tracking down intermittent bugs or analyzing issues after they happen.

Note: The log file won’t be created until an actual error is triggered — so don’t worry if it doesn’t appear right away.

🙈 Disabling On-Screen Errors with WP_DEBUG_DISPLAY

If you’re debugging on a live or semi-public environment, you probably don’t want errors splattered across your site. You can suppress them with:

define( 'WP_DEBUG_DISPLAY', false );

This way, errors are quietly logged but not shown to users.

🧪 Other Useful Debug Constants

  • SCRIPT_DEBUG: Forces WordPress to use non-minified versions of core JS and CSS files. Great for debugging script issues. 
    define( 'SCRIPT_DEBUG', true );
  • SAVEQUERIES: Logs all database queries for the current request. Often used with Query Monitor to spot performance issues. 
    define( 'SAVEQUERIES', true );

⚠️ WP_DEBUG and Production Sites

It’s best to keep WP_DEBUG turned off on live sites unless you’re working through a very specific issue. If you must enable it temporarily, always use WP_DEBUG_DISPLAY set to false and monitor debug.log discreetly.

Quick tip: Use environment-specific configurations to toggle debugging in dev but disable it in production — tools like Bedrock or even simple conditionals in wp-config.php can help.

Once you’ve enabled and configured WP_DEBUG properly, you’ll start uncovering the invisible signals WordPress has been sending you all along — and that’s the first real step toward smart, systematic debugging. 🧭

🗂️ Exploring the Error Log

Once you’ve enabled WP_DEBUG_LOG, WordPress will begin saving PHP errors to a file called debug.log inside your wp-content directory. This log is your behind-the-scenes journal of everything that’s going wrong — or almost going wrong — with your site.

Reading and understanding this log is a key part of becoming a confident debugger.

📍 Where to Find the Error Log

By default, WordPress writes to:

wp-content/debug.log

You can open this file in any text editor or IDE. If you don’t see the file, make sure:

  • WP_DEBUG and WP_DEBUG_LOG are both set to true
  • Errors are actually occurring — the file isn’t created until the first error happens
  • Your web server (e.g. Apache or Nginx) has permission to write to the wp-content directory

🔍 Reading Log Entries

A single log entry might look like this:

[19-May-2025 12:03:45 UTC] PHP Warning:  Undefined variable $title in /wp-content/themes/mytheme/header.php on line 22

Let’s break that down:

  • Date & Time: Helps you correlate errors with recent changes or requests
  • Error Type: In this case, a PHP Warning
  • Message: What went wrong and where
  • File & Line: The exact location of the issue

Pro tip: Don’t ignore notices and warnings. They’re often early indicators of bugs that may break things later.

🧭 Finding the Root Cause

If you see an error in a theme or plugin file, go to that file and examine the line mentioned. Ask yourself:

  • Is the variable or function defined?
  • Is it being used before it’s ready?
  • Was there a recent update that might’ve introduced the issue?

Sometimes, the issue originates elsewhere — an earlier function might fail silently and cause a chain reaction. That’s where the full log history becomes helpful: scroll up and look at surrounding entries.

🧹 Filtering Through the Noise

Large debug logs can become overwhelming, especially on busy or poorly optimized sites. To manage this:

  • Clear the file periodically to start fresh (just delete its contents, not the file itself)
  • Temporarily deactivate noisy plugins to isolate real problems
  • Use your editor’s search to look for key terms like Fatal, Undefined, or specific file names

📎 Server Logs Beyond WordPress

In addition to debug.log, your server might be writing its own logs. These can capture:

  • PHP fatal errors (even before WordPress loads)
  • Memory limit issues
  • Permission problems

Check with your hosting provider or server admin to locate these — they’re usually in a directory like /var/log or accessible via a hosting panel (e.g. cPanel → Errors).

Remember: The error log isn’t just for “when things break.” It’s a powerful real-time insight into how your code is behaving — and misbehaving — under the hood.

🧪 Using the Query Monitor Plugin

Query Monitor is often described as the “X-ray vision” for WordPress. Once activated, it gives you a detailed look into what’s happening during each page load — from database queries to hooks, HTTP requests, and more.

It’s one of the most essential tools for WordPress developers who want to go beyond basic debugging and truly understand performance and behavior issues.

🚀 Installing Query Monitor

You can install it like any other plugin:

  1. Go to Plugins → Add New
  2. Search for “Query Monitor”
  3. Click Install and then Activate

Once it’s active, a new menu appears in the WordPress admin bar whenever you’re logged in and viewing the site.

🔎 What You Can Inspect

Clicking the Query Monitor menu reveals a panel with a goldmine of information. Here are some highlights:

  • Database Queries: See every SQL query triggered by the current page, how long each one took, and where it came from in the code.
  • Hooks & Actions: Discover which filters and actions fired during the request — and in what order.
  • PHP Errors: View notices, warnings, and deprecations — even if they’re not displayed on screen.
  • Scripts & Styles: Identify all enqueued JavaScript and CSS files, including their sources and dependencies.
  • HTTP API Calls: Monitor external requests made by the site, including status codes and durations.
  • Environment Details: Check your PHP version, memory usage, active theme, and loaded plugins.

📊 Diagnosing Performance Issues

Query Monitor is especially useful for spotting slow database queries or overloaded templates. If a page feels sluggish, open the “Queries by Component” or “Duplicate Queries” tabs. You’ll quickly see what’s hogging resources.

Example: You might find that a plugin is making 20 identical queries on a single page. That’s a clue it needs optimization or replacement.

🧩 Working with Custom Code

If you’re writing your own plugin or theme functions, Query Monitor helps ensure they behave well. You can:

  • Track where your custom queries are running
  • Monitor any errors thrown by your functions
  • Verify that your custom hooks are firing in the expected order

🔐 Viewing as Logged-In User Only

By default, only logged-in users with admin privileges see Query Monitor’s output. This keeps debugging data hidden from public view — a smart security feature you don’t need to configure manually.

💡 Tip: Combine with WP_DEBUG_LOG

For the best of both worlds, keep WP_DEBUG_LOG enabled alongside Query Monitor. That way, you get real-time visual feedback plus a persistent record in case something slips by.

Once you get comfortable with Query Monitor, you’ll wonder how you ever developed or debugged without it. It’s truly one of the most valuable tools in the WordPress ecosystem.

🔍 Diagnosing Plugin and Theme Conflicts

One of the most common causes of strange WordPress behavior is a conflict between plugins or themes. You might install a new plugin and suddenly your contact form stops working — or a style gets wiped out. These conflicts can be subtle or site-breaking, and learning to track them down is a must-have skill.

⚔️ What Does a Conflict Look Like?

Conflicts often manifest as:

  • JavaScript errors in the browser console
  • Broken layouts or missing styles
  • Features suddenly not responding (e.g. AJAX fails, buttons stop working)
  • Errors thrown in debug.log that point to plugin or theme files

Tip: If a problem appeared right after you activated or updated a plugin or theme, it’s probably not a coincidence.

🪜 How to Systematically Identify a Conflict

The most effective method is called a conflict test. Here’s how to do it step by step:

  1. Switch to a default theme like Twenty Twenty-Four.
  2. Deactivate all plugins.
  3. Check if the issue is gone. If so, it’s definitely a theme or plugin conflict.
  4. Reactivate plugins one at a time, refreshing the site after each one. The moment the issue returns, you’ve found the culprit.

Yes, it’s manual — but it’s incredibly effective. This method isolates exactly what’s triggering the problem.

🧪 Tips for Smoother Conflict Testing

  • Use a staging site: Always run conflict tests in a safe environment. Never debug by deactivating plugins on a live production site.
  • Clear caches: If you’re using a caching plugin or server-side caching (like Varnish), clear them before each check.
  • Use health check mode: The Health Check & Troubleshooting plugin lets you simulate plugin/theme deactivation just for your logged-in session. Great for debugging without affecting site visitors.

🤝 Common Types of Conflicts

Some of the most frequent causes of conflicts include:

  • Two plugins trying to load the same JavaScript library in different versions
  • A theme that overrides default WooCommerce templates in a way that breaks a plugin
  • Multiple plugins hooking into the same action and interfering with each other’s logic

🧰 Debugging the Conflict

Once you’ve found the conflicting plugin or theme, you have a few options:

  • Look in debug.log for related PHP errors
  • Use Query Monitor to inspect database queries, hooks, or HTTP calls
  • Open the browser’s Developer Tools → Console to view JavaScript errors

If it’s your own custom code, this is your chance to patch it. If it’s a third-party tool, you can reach out to the developer with a precise bug report.

Good bug reports describe exactly when the problem happens, what errors show, and how to reproduce it. Devs will ❤️ you for it.

With practice, plugin and theme conflicts will become less of a mystery and more of a detective game — one you’ll get faster and better at solving with time. 🕵️‍♂️

🧯 Interpreting JavaScript Console Errors

Not all WordPress issues stem from PHP or server-side problems — a surprising number arise from JavaScript errors in the browser. If buttons stop working, sliders break, or AJAX features fail silently, the browser console is the first place to look.

🖥️ Opening the Browser Console

Every modern browser has built-in developer tools. Here’s how to open the JavaScript console:

  • Chrome / Edge: Right-click → Inspect → Console tab
  • Firefox: Right-click → Inspect Element → Console tab
  • Safari: Develop → Show JavaScript Console (enable Develop menu in preferences if hidden)

You’ll see a live stream of messages, errors, warnings, and logs — many of which come directly from your WordPress site’s scripts.

🚨 Common JavaScript Error Types

  • Uncaught ReferenceError: A variable or function is used before it’s defined
  • TypeError: You’re trying to call something that isn’t a function (or access something that isn’t an object)
  • SyntaxError: There’s a typo or formatting mistake in your JavaScript code
  • CORS Errors: Cross-origin requests are blocked due to security policies

Example: Uncaught TypeError: $ is not a function — this often means jQuery hasn’t loaded or is in noConflict mode.

🔍 Reading a Console Error

Here’s an example of what a real error might look like:

Uncaught TypeError: Cannot read properties of undefined (reading 'addClass')
    at custom-script.js:25
    at custom-script.js:50

This tells us:

  • The error is a TypeError
  • It happened in custom-script.js at line 25
  • The script is trying to access something that doesn’t exist (likely a jQuery selector that failed)

Clicking the filename will take you directly to the source code in the browser so you can inspect it in context.

💥 JavaScript Conflicts in WordPress

WordPress loads many scripts — jQuery, jQuery UI, AJAX handlers, and more. Plugins and themes may load their own versions too, which can lead to:

  • Multiple versions of jQuery conflicting
  • Code executing before the DOM is ready
  • Third-party libraries overwriting global variables

To avoid these issues, always:

  • Enqueue your scripts properly using wp_enqueue_script
  • Wrap code in jQuery(document).ready() or use DOMContentLoaded events
  • Use console.log() for temporary debugging during development

📦 Minified Files and Debugging

If you’re seeing errors in minified files (like script.min.js), they’ll be harder to interpret. Here’s what you can do:

  • Enable SCRIPT_DEBUG in wp-config.php:
define( 'SCRIPT_DEBUG', true );

This tells WordPress to load the non-minified versions of core scripts, which are easier to debug.

🧰 Tools That Help

In addition to the browser console, you might find these helpful:

  • Lighthouse: Built into Chrome DevTools, helps identify performance and script issues
  • Debugger statements: Add debugger; in your JS to pause execution and inspect state
  • Query Monitor: Helps catch server-side script enqueuing and AJAX errors

JavaScript errors can seem cryptic at first, but once you get the hang of reading the console, they become invaluable clues — guiding you straight to the root of client-side bugs. 🔦

🗃️ Debugging Database Issues

The WordPress database is the heart of your site — it stores everything from posts and pages to settings, metadata, and plugin data. When something goes wrong with the database, the results can range from subtle content issues to full-blown site crashes.

Understanding how to diagnose and resolve these issues will save you hours of frustration and help you work more confidently with custom queries, plugins, and migrations.

🧵 Spotting Signs of a Database Problem

Some common symptoms that hint at a database issue include:

  • Posts or settings mysteriously not saving
  • White screen or Error establishing a database connection
  • Broken admin areas or missing menus
  • Slow queries or timeout errors

When in doubt, always check both the browser console and your debug.log. Some database-related issues only surface server-side.

🔍 Enabling Query Logging

One of the best tools for uncovering problematic queries is Query Monitor (covered earlier). Once enabled, you can see:

  • All queries run on a page
  • How long each query took
  • Which plugin or theme file issued the query
  • Which queries were duplicated or inefficient

This is extremely helpful when debugging slow or non-performant areas of your site, like a WooCommerce product archive or a custom dashboard.

⚙️ Checking wp-config.php Settings

Make sure the database credentials are correct:

define( 'DB_NAME', 'your_db_name' );
define( 'DB_USER', 'your_db_user' );
define( 'DB_PASSWORD', 'your_db_password' );
define( 'DB_HOST', 'localhost' );

If you’re seeing a “Cannot connect to database” error, incorrect credentials or a downed database server is usually the culprit.

🧪 Fixing Corrupted Tables

Sometimes tables can get corrupted, especially on shared hosting environments. If you suspect this:

  1. Log into phpMyAdmin or your database management tool
  2. Select your WordPress database
  3. Check all tables → Choose “Repair table” from the dropdown

Alternatively, you can enable WordPress’s built-in repair tool by adding this to your wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Then visit: https://yoursite.com/wp-admin/maint/repair.php

Warning: This tool is public. Only enable it temporarily and remove the line from wp-config.php after use.

🔐 Check for Escaping & SQL Injection

If you’re writing custom queries, ensure you’re using WordPress’s built-in escaping and preparation functions to prevent SQL injection and broken queries:

$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}posts WHERE post_status = %s",
        'publish'
    )
);

Incorrect or unescaped inputs can lead to syntax errors or even break your site’s data integrity. Always sanitize and validate input from users.

🧼 Clean Up the Clutter

Over time, plugins may leave behind orphaned data — old transients, unused options, or broken foreign key references. Consider these tools to clean up your database:

  • WP Optimize – for removing stale revisions and transients
  • Advanced Database Cleaner – for finding orphaned tables and scheduled tasks

Be cautious when cleaning — always back up your database before making any changes.

☁️ Hosting-Specific Considerations

Some managed hosts like WP Engine or Kinsta provide database insights directly in their dashboards. Others may restrict certain queries or table sizes. If you’re unsure whether a slow query is being caused by your code or your server, don’t hesitate to ask your host — many have tools for monitoring MySQL performance.

With practice, you’ll learn to spot red flags and fine-tune how WordPress interacts with the database — making your site faster, more stable, and easier to maintain. 💪

🛠️ Debugging with Browser Developer Tools

Browser Developer Tools are a developer’s best friend — an all-in-one suite that lets you inspect, modify, and troubleshoot your WordPress site directly from the browser. They provide a real-time window into your site’s HTML, CSS, JavaScript, network activity, and much more.

🔍 Inspecting HTML & CSS

When something looks off visually — a broken layout, misaligned button, or hidden element — start by right-clicking the element and selecting Inspect. This opens the Elements panel where you can:

  • See the exact HTML structure
  • Check CSS rules applied and their sources
  • Toggle CSS properties on and off to test fixes instantly
  • Experiment with live edits to styles without changing your files

Tip: Use the “Computed” tab to understand what styles are actually being applied after all cascading and inheritance.

🌐 Monitoring Network Requests

The Network panel shows every file your browser requests while loading a page — including images, scripts, stylesheets, and AJAX calls. This is essential for debugging:

  • Slow-loading assets that might delay page rendering
  • Failed requests that return 404 or 500 errors
  • AJAX responses to verify data being returned

Look for red-highlighted items to spot problems quickly. Clicking a request shows detailed headers, response data, and timing information.

⚙️ Debugging JavaScript Interactively

Beyond the Console, the Sources panel lets you:

  • Set breakpoints to pause script execution at specific lines
  • Step through your JavaScript code line by line
  • Examine the current state of variables and call stacks
  • Use the Watch feature to monitor variables in real-time

This is invaluable for hunting down tricky bugs or understanding complex asynchronous flows like AJAX calls or event handlers.

🖥️ Emulating Devices and Screen Sizes

The Device Toolbar allows you to simulate different screen sizes, resolutions, and even network conditions. This helps you test your site’s responsive design and performance on mobile or slow connections.

🧹 Clearing Cache & Disabling Extensions

If your changes aren’t showing up or things behave unpredictably, try:

  • Clearing the browser cache
  • Disabling browser extensions that might interfere with site scripts
  • Using Incognito/Private mode to test without stored cookies or cache

🛡️ Security and Privacy Considerations

Keep in mind that Developer Tools reveal sensitive data like cookies, API keys, or user tokens. Don’t share screenshots or logs publicly without redacting these.

Mastering browser developer tools takes time, but it unlocks deep insight into your site’s frontend behavior — making debugging faster, more precise, and often even enjoyable. 🔧

🛠️ Debugging REST API Issues

The WordPress REST API powers many modern themes, plugins, and integrations — from the block editor to headless setups. When things go wrong with the API, it can break dynamic content, data syncs, or third-party connections.

🔎 How to Identify REST API Problems

Common signs include:

  • Block editor (Gutenberg) failing to load or save content
  • Frontend features that rely on AJAX requests not updating
  • Third-party apps or mobile clients not syncing data
  • Errors logged in the browser console referencing /wp-json/ endpoints

🛠️ Testing API Endpoints Directly

You can test any REST API endpoint by visiting it in your browser or using tools like Postman or cURL. For example:

https://yoursite.com/wp-json/wp/v2/posts

This should return a JSON list of your latest posts. If you get a 404, 401, or 500 error, there’s a problem.

🔧 Common Causes of REST API Issues

  • Permalink structure problems: The API relies on pretty permalinks. Make sure Settings → Permalinks uses a non-default structure.
  • Security plugins or firewalls: Sometimes these block REST requests mistakenly.
  • Authentication issues: Endpoints that require authorization may fail if tokens or cookies are missing or invalid.
  • Rewrite rules: Sometimes rewrite rules get corrupted and need to be flushed.

💡 How to Fix REST API Problems

  • Go to Settings → Permalinks and click “Save Changes” to flush rewrite rules
  • Temporarily deactivate security plugins or firewalls to test if they’re blocking REST requests
  • Check the browser console and server error logs for related messages
  • Use tools like wp_remote_get() in custom code to test API calls programmatically

📡 Monitoring REST API Traffic

Plugins like Query Monitor can track REST API requests and highlight failures. Additionally, server logs (e.g., Apache or NGINX) can provide insights on blocked or malformed requests.

🔐 Authentication and Permissions

Some REST endpoints require authentication. Make sure your API clients:

  • Use the correct nonce or OAuth tokens
  • Have sufficient user permissions
  • Follow the latest WordPress REST API standards

When debugging, you can temporarily switch to a user with administrator privileges to isolate permission issues.

Mastering REST API debugging will empower you to build, troubleshoot, and maintain modern WordPress sites with confidence — opening doors to powerful integrations and headless architectures. 🚀

🤝 When to Seek Help and Useful Resources

Debugging WordPress can sometimes feel like navigating a maze — especially when you hit tricky bugs or complex server issues. Knowing when and where to ask for help is just as important as knowing how to debug.

🆘 Signs You Should Seek Help

  • Errors persist despite thorough troubleshooting
  • Database corruption or critical site downtime
  • Issues involving server configuration or hosting environment
  • Complex plugin or theme conflicts that aren’t easy to isolate
  • Security breaches or suspicious activity

Remember, WordPress has a vast and friendly community ready to support you!

🌐 Top Resources for WordPress Debugging Help

👥 Professional Help Options

If you’re facing critical issues or tight deadlines, consider:

  • Hiring experienced WordPress developers — many freelancers specialize in debugging and performance optimization
  • Using managed WordPress hosting — many hosts offer expert support for troubleshooting
  • Consulting WordPress maintenance services — ongoing support plans can prevent problems before they start

And finally — don’t forget to share your knowledge. Helping others debug strengthens the entire community! 🌱