The Ultimate WordPress Debugging Guide  ## Metadata - Author: [[Remkus]] - Full Title: The Ultimate WordPress Debugging Guide - Category: #articles - Document Note: --- tags: [WordPress, Debugging, Performance] author: Remkus source: remkusdevries.com reference: [https://remkusdevries.com/wordpress-debugging-guide/] date created: 2025-11-06 00:00 --- # 🏷️ Title: The Ultimate WordPress Debugging Guide ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - WordPress constants for debugging (developer.wordpress.org/apis/wp-config-php/) - WP-CLI overview (wp-cli.org) - Query Monitor plugin (wordpress.org/plugins/query-monitor/) - Health Check & Troubleshooting plugin (wordpress.org/plugins/health-check/) - Using Xdebug with WordPress (xdebug.org) - WordPress Site Health (wordpress.org/support/article/site-health-screen/) ## 📝 Summary - What happened: A step-by-step WordPress debugging playbook from quick checks to CLI and developer-level tooling. - Why it matters: Reduces downtime, pinpoints root causes, and improves site reliability and performance. - Key stakeholders: Site owners, developers, hosts, support teams. - Risks and tradeoffs: Enabling verbose debugging in production, misconfiguring resources, partial fixes that mask root causes. - Bottom line: Start simple (cache/theme/plugins), collect evidence (logs/devtools/site health), then escalate with WP-CLI, profiling, and code tracing. ## 📖 Main Content - Core arguments: - Most issues have clear breadcrumbs—start with caching, theme/plugin isolation, and browser checks. - Turn on safe server-side logging to avoid exposing errors to users. - Use DevTools (Console/Network) and WordPress Site Health for quick signal. - For deeper work, lean on server logs, WP-CLI (plugin toggles, health, profiling), and resource checks. - Developer tools (Query Monitor, Debug Bar, Xdebug/Ray) reveal bottlenecks and failing code paths. - Context/definitions: - WSOD: blank page from fatal PHP errors; isolate via logs and plugin/theme disable. - Error types: Fatal (halts execution) vs Notice (non-blocking) vs Deprecated (future-removal warnings). - Uncertainties/contested: - Memory limits and perf thresholds vary by host/traffic. - Verbose plugin logging can obscure critical errors; triage is essential. ### 🗒️ Notes - Pre-flight: backups, timeframe/baselines, staging, host metrics (CPU/mem/I/O). - Simple fixes: clear browser/site cache, incognito, disable optimizers, switch to Twenty Twenty-Five, Health Check “Troubleshooting Mode.” - Logging: enable WP_DEBUG with log-to-file; review wp-content/debug.log; hide display in production. - DevTools: check Console (JS errors) and Network (4xx/5xx, blocked/slow requests). - Site Health: gather environment; copy system info for support. - Server logs: Apache/Nginx error logs; tail -f for live errors. - Isolation: batch reactivate plugins (“divide and conquer”); switch theme; use WP-CLI for speed. - WP-CLI: plugin list/deactivate/activate; wp doctor; wp profile stage; db check; transient list/delete-expired; cron event list/run. - Performance: raise memory (cautiously), profile load stages, identify heavy queries/hooks. - Developer mode: Query Monitor, Debug Bar; SAVEQUERIES, SCRIPT_DEBUG, environment type; trace with Xdebug/Ray; local stacks (LocalWP, Lando, DevKinsta). - REST/AJAX: inspect /wp-json/ and admin-ajax.php responses; use Postman/curl. - FAQs: WSOD, fatal vs notice, deprecated, blank-after-update rollbacks, missing debug logs, noisy logs triage. ## 📚 References - WordPress debugging in wp-config.php (https://developer.wordpress.org/apis/wp-config-php/) - WP-CLI commands (https://wp-cli.org/) - Query Monitor (https://wordpress.org/plugins/query-monitor/) - Health Check & Troubleshooting (https://wordpress.org/plugins/health-check/) - Xdebug docs (https://xdebug.org/docs/) - Site Health Screen (https://wordpress.org/support/article/site-health-screen/) ## 🗣️ Paraphrase - Paragraph A: Debugging WordPress is systematic—follow breadcrumbs from simple cache/theme/plugin checks to logs and tools that reveal the true cause. - Paragraph B: With WP-CLI, profiling, and developer debuggers, you can isolate conflicts, fix performance issues, and understand how WordPress executes your code. ## 📰 Newsletter Level up your WordPress debugging: start with Health Check’s Troubleshooting Mode, flip on safe logging, and use DevTools to spot JS and network fails. Then go pro with WP-CLI (wp doctor, wp profile), Query Monitor for slow queries/hooks, and Xdebug for true step-through tracing. Bonus: keep a staging clone and baseline metrics—future you will thank you. Useful links: Query Monitor, Health Check, WP-CLI. ## ✅ Action Items #### DevRel - Publish “Debugging WordPress 101/201” guides, live demos of WP-CLI profiling, and office hours. - Ship examples: minimal mu-plugin to log hooks; wp profile sample reports. - Campaign: “Logs or it didn’t happen” with reproducible bug templates. #### OSPO - Standardize debugging policies; require staging + Site Health info for support. - License scanning for debugging plugins; set update cadence for tooling. #### Community - Maintainer clinics on profiling and transient hygiene. - Contributor pairing on reproductions and minimal test cases. - Sponsors: fund perf bounties and profiling dashboards. #### WordPress - Core: document perf budgets; improve Site Health signals for cron/transients. - Core Performance: public dashboards; query/hook heatmaps. - Core AI: none specific; ensure logs exclude sensitive data in AI tooling. - Core Program Team: share reproducible bug templates. - Playground: add “WSOD lab” recipes. - Training: create lessons on DevTools/CLI tracing. - Marketing: highlight “staging-first” update stories. - Support: enforce environment bundle (Site Health copy + debug.log). - Documentation: examples-first patterns for WP_DEBUG, WP-CLI profiling. - Accessibility: test admin notices and debug UI contrast. - Hosting: default log retention, live tailing, WP-CLI availability. #### The WPCC - Microgrants for profiling critical plugins. - Docs sprints: debugging checklists for small businesses. ### FAIR - Provenance: sign builds; log integrity. - Policies: transparent funding of perf work; sunset stale tools. - Governance artifacts: incident runbooks, perf scorecards. ## 🧪 Hypotheses - Enabling safe file logging reduces time-to-resolution by ≥30%. - WP-CLI batch isolation halves mean time to identify conflicting plugins. - Query Monitor adoption correlates with ≥20% fewer unresolved perf tickets. - Staging-first updates reduce WSOD incidents by ≥50%. ### 📊 Methodology - A/B across support tickets: logging vs none; measure TTR. - Time boxed debugging trials: dashboard-only vs WP-CLI. - Telemetry from sites using Query Monitor (opt-in) vs control. - Incident reviews pre/post staging policy adoption. ### ❓ Questions - Which WP-CLI checks most strongly predict critical failures? - How much memory headroom prevents common timeouts per traffic tier? - What minimal logs best balance privacy and debuggability? ### 🔮 Future Research - Automated “conflict bisection” in the dashboard. - Built-in transient/cron health visualizations. - First-party structured error reporting to Site Health. ### 💡 Implications - Practice: normalize staging and reproducible reports. - Policy: hosts should expose logs and WP-CLI by default. - Security: ensure logs exclude secrets; set retention. - Education: core lessons on profiling and REST/AJAX debugging. - Funding: sponsor perf profiling of top plugins. ### 🧠 Learning Styles Assessment - Reading level: Flesch-Kincaid Grade ≈ 9–10. #### 👀 Visual learners - Present: menus, tools, commands. - Impro - Summary: 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 […] - URL: https://remkusdevries.com/wordpress-debugging-guide/ Background pattern 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](https://remkusdevries.com/wordpress-debugging-guide/#comment-23946), for suggesting this pre-flight checklist! 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. 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](https://remkusdevries.com/wordpress-debugging-guide/#comment-23944), 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.](https://wordpress.org/plugins/health-check/) 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 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. 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 ``` ##### 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. #### 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](https://remkusdevries.com/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 | | 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. #### Stay in the Loop Whether you’re here for personal reflections or deep WordPress insights, there’s more where this came from. I write two newsletters worth your time. Each serving a different part of my brain (and maybe yours too). If you’re serious about building faster, more secure, and more reliable WordPress sites, this newsletter is for you. I focus on the news around tools, plugins, and practices that power professional-grade WordPress sites. This is my personal newsletter where I share things I blog about, ideas I’m exploring, books I’m reading, tools I’m testing, and the occasional strong opinion loosely held., The Ultimate WordPress Debugging Guide, Remkus, 01k9d17dtgy9gycjym0fengha0.