Query Monitor for WordPress: Complete Developer Tutorial (Every Panel Explained)
Query Monitor 4 panel by panel: slow and duplicate queries, hooks, HTTP calls, errors, plus AJAX and REST debugging. Tested on 4.1.1 and WordPress 7.1.4.

Query Monitor is a free developer panel for WordPress that shows, for the page you are looking at, every database query, hook, HTTP call, PHP error, script, template and capability check that ran. Install it, log in as an administrator, and click the new item in the admin toolbar. The fastest first use is the Database Queries panel: sort by time, look for rows flagged as slow, and read the Caller column to see which plugin or theme issued them.
We tested everything below on 16 Nov 2026 with Query Monitor 4.1.1 (last updated 27 Oct 2026) on WordPress 7.1.4, PHP 8.3, Apache and MariaDB 11. Query Monitor 4 was a large rewrite, so many older tutorials, including the earlier version of this post, describe panels and settings that no longer exist. Where we correct something, we say so. We could not take interface screenshots for this refresh, so panel descriptions come from the plugin source, the official documentation and data we pulled from the plugin’s own JSON output.
What is Query Monitor, and who can see its output?
Query Monitor is a plugin by John Blackbourn. On 16 Nov 2026 the WordPress.org listing showed version 4.1.1, “tested up to” WordPress 7.1.4, a minimum of WordPress 6.3 and PHP 7.4, more than 200,000 active installs, and a 98 out of 100 rating from 470 reviews (we read these from the plugin page and its API). The readme says it is private by default: it does not store the data it collects persistently, and it sends nothing to a third party.
Who sees the output is a capability question. On a single site, view_query_monitor is granted at runtime to any user who can manage_options, which means administrators. On multisite, only super admins get it. You can also set an authentication cookie from the plugin’s Settings panel, which lets a person see the output while logged out or as a non-administrator. Hosts that bundle the plugin can change this: the readme notes that WordPress VIP requires the capability to be granted explicitly, even to administrators.
Query Monitor only runs when PHP runs. A page served by a full-page cache before WordPress loads has no Query Monitor data, and nothing is added for logged-out visitors who do not hold the cookie.
How do I install it and turn on the extra data?
# Checked on 16 Nov 2026, WP-CLI 2.12
wp plugin install query-monitor --activate
wp plugin get query-monitor --fields=name,version,status
# name query-monitor
# version 4.1.1
# status activeOn activation the plugin tries to create a symlink at wp-content/db.php. That file is a WordPress drop-in that lets Query Monitor see every database query with its result count and full stack trace. Without it, the official help page says the plugin still works, but you lose the extended information: result counts, full stack traces, and error detection for all queries. On our test site the symlink existed after activation. If wp-content is not writable, make it writable and reactivate the plugin, or run wp qm enable, which we confirmed is a real WP-CLI command.
Another drop-in can block the link, because only one file can sit at wp-content/db.php. The help page names W3 Total Cache, LudicrousDB, HyperDB and the SQLite Database Integration plugin as common causes. After a site migration, an old symlink can also point at a path that no longer exists, so recreate it.
A handful of constants change behaviour. These defaults match both the official list and the source we read:
Constant | Default | What it does |
|---|---|---|
|
| A single query slower than this is flagged as slow |
|
| Turns the plugin off entirely |
|
| Stops Query Monitor handling PHP errors |
|
| Turns on the Capability Checks panel |
|
| Hides WordPress core from the Hooks panel |
|
| Hides Query Monitor’s own entries from its panels |
|
| Shows every hook that has callbacks, not only actions that fired |
|
| Allows the |
Set them in wp-config.php. Two older settings that guides still repeat do not exist in 4.1.1: a qm/slow-query-threshold filter (the slow-query limit is the QM_DB_EXPENSIVE constant) and a qm/enable-rest query parameter. We searched the plugin source for both and found neither.
What changed in Query Monitor 4?
The Query Monitor 4 page lists the changes. The panels now render in the browser instead of in PHP, which the plugin author says greatly improves performance on pages with many queries or errors. A new Timeline panel plots queries, HTTP requests, PHP errors, timings, logs and notable actions on one horizontal timeline, with filtering by component. The bundle no longer uses jQuery or the wp global and does not enqueue its assets. The collected data is available to the page as a QueryMonitorData object that you can inspect in the browser console. Panels added by third-party plugins should keep working, but third parties cannot register client-side panels yet.
For you as a reader of tutorials, this has three effects. Panel names differ from older guides (the cache panel is “Object Cache” and the capability panel is “Capability Checks”). Some panels are optional or conditional. And a few reported problems are specific to version 4, which we list near the end.
Which Query Monitor panel answers which question?
Use this table as a cheat sheet. The panel names come from the plugin source for version 4.1.1.
Your question | Panel | What to look at |
|---|---|---|
Why is this page slow overall? | Overview and Timeline | Total time, memory, query time, and where the time falls on the timeline |
Which query is slow or repeated? | Database Queries, Queries by Caller, Queries by Component, Duplicate Queries | Time, rows, caller, component, repeated SQL |
Which callback changes this value? | Hooks & Actions | Callbacks, priorities and components on a named hook |
Which request goes out to another server? | HTTP API Calls | URL, status or error, time, responsible component |
Why did my code log an error? | PHP Errors and Doing it Wrong | Message, file, line, call stack, component |
Which template file rendered this page? | Theme and Request | Template, hierarchy, matched rewrite rule, query vars |
Why does this script or style load here? | Scripts and Styles | Handle, dependencies, dependents, broken dependencies |
Why is a string not translated? | Languages | Loaded .mo and JSON files per text domain |
What does this conditional return? | Conditionals | True or false for each conditional function |
Which server settings am I on? | Environment | PHP, database, WordPress, web server details |
Why was access denied? | Capability Checks (opt-in) | Each capability check, its result and arguments |
Is the object cache helping? | Object Cache | Hits, misses, hit percentage |
What did my own code log or time? | Logger and Timing | Messages by level, named timers and laps |
Which transients were set? | Transients | Transients updated during the request |
How do I find slow and duplicate queries?
Open Database Queries. Each row shows the SQL, the time, the rows returned, and a call stack from the function that issued it up to WordPress core. Rows slower than the QM_DB_EXPENSIVE limit are flagged, and the toolbar shows a count. The same data is grouped three other ways: by calling function, by component (plugin, theme or core), and as a list of duplicates.
We checked the numbers by running a controlled request. A test hook ran the same SELECT COUNT(*) three times, one SELECT SLEEP(0.08), and one query against a table that does not exist. Query Monitor’s own data for that request recorded 22 queries in 0.088 seconds. The sleep query measured 0.0822 seconds, above the 0.05 default, so it would be flagged. The three identical counts took 0.0006, 0.0003 and 0.0002 seconds, which is the point: repeated queries often look cheap one by one, and the cost is in their number. The query against the missing table was recorded with its error.
Read the results in this order:
- Component view first. It tells you which plugin or theme owns most of the query time. Start with the largest.
- Duplicates next. Identical SQL run several times usually means missing caching, a loop that calls
get_option()orget_post_meta()per item, or a widget run twice. Fix the loop, not the query. - Slow rows last. For each flagged query, check that the
WHEREcolumn is indexed, thatLIKEdoes not start with a wildcard, and that you are not scanningwp_postmetaorwp_optionswithout a narrow filter. - Errors. A failed query shows an error message. Without the
db.phpdrop-in, Query Monitor cannot detect errors for all queries.
Do not treat “more than 100 queries” as a fixed threshold. A page with WooCommerce and a membership plugin can run many cheap, cached queries and still be fast. Use counts to find the odd one out, and use time to decide what matters. Our guide to reducing time to first byte covers what to do after you have found the cost.
How do I see which callbacks hook into a filter or action?
Open Hooks & Actions and search for the hook name. For each hook you see the attached callbacks, their priorities, and the component each one belongs to. This answers “who changes the post content” or “why does my callback run after another plugin’s”.
One detail trips people up. By default the panel lists only action hooks that fired during the request. We read the collector: with default settings it iterates the actions that have run, and only when QM_SHOW_ALL_HOOKS is true does it list every hook with callbacks, including filters, and rename the panel “Hooks, Actions, & Filters”. If a filter such as the_content or theme_mod_{$name} is missing, define the constant. QM_HIDE_CORE_ACTIONS removes WordPress core from the list when you want to see only plugins and your theme.
If a callback on a dynamic hook never appears, the hook name is usually wrong by one character. We walk through that, including how dynamic names are built and which ones fire in which order, in our guide to dynamic hooks and save_post_{type}.
How do I find slow or failing outbound HTTP calls?
HTTP API Calls lists every request WordPress makes through its HTTP API during the page load: update checks, license checks, payment or CRM calls, remote fonts fetched server-side, and anything else that uses wp_remote_get() or wp_remote_post(). For each call it shows the URL, method, response code or error, time, and the component that made it. Failed or erroneous requests are highlighted.
We made a call to a closed port inside a test request. The data came back with the URL, method: GET, the response string cURL error 7: Failed to connect to 127.0.0.1 port 9, and a time of 0.0023 seconds. A slow third-party API shows up the same way with a large time value. Any synchronous call on a page that must render fast is a candidate to move into a background job.
To see which plugins try to reach the internet, you can block external requests on a development copy. We set WP_HTTP_BLOCK_EXTERNAL to true and requested https://example.com/. WordPress returned the error code http_request_not_executed with the message “User has blocked requests through HTTP to the URL”. Add hosts you still need to WP_ACCESSIBLE_HOSTS. Remove the constant afterwards, because blocking requests breaks update checks and licensing.
// Checked on 16 Nov 2026, WordPress 7.1.4. Development copies only.
define( 'WP_HTTP_BLOCK_EXTERNAL', true );
define( 'WP_ACCESSIBLE_HOSTS', 'api.wordpress.org,*.github.com' );How do I read PHP errors, Doing it Wrong notices and wp_die calls?
PHP Errors captures errors with their message, file, line, full call stack and the component responsible, whatever your php.ini says about display. Doing it Wrong collects _doing_it_wrong() notices and deprecated usage, attributed to the plugin or theme that triggered them. The toolbar shows a visible warning when errors exist, so you do not need to open a panel to know something is wrong.
If you want Query Monitor to stay out of PHP error handling, QM_DISABLE_ERROR_HANDLER turns its handler off. Our guide to why debug.log stays empty covers the log-file side, which Query Monitor does not replace.
The wp_die() page of the documentation covers the case where WordPress stops a request with wp_die() and you need the call stack that led there.
How do I find which template file rendered a page?
Open Theme for the template filename, the template hierarchy that WordPress checked, and the names of template parts that did or did not load. This works for classic and block themes. Open Request for the matched rewrite rule, the query string it produced, and the query variables passed to WP_Query. Use both when a custom rewrite rule or a custom query variable does not do what you expect: confirm the URL maps to the variables you intended before you debug the query itself.
The Conditionals panel prints the result of every conditional function, such as is_single() and is_page(), for the current request, so you do not need var_dump calls in a template. Admin Screen shows the screen ID, base and related fields on admin pages. That ID is what you need for screen-based hooks such as manage_{$screen->id}_columns. For a post type list table the ID is edit- followed by the post type slug, which we confirmed in our dynamic hooks tests. Environment shows PHP, database, WordPress and web server details, which is the first place to look when something works locally and not on staging.
How do I debug scripts, styles and translations?
Scripts and Styles list each enqueued asset with its handle, source, dependencies and dependents, and alert you to broken dependencies. In version 4 they became separate panels, and some users thought the Scripts panel had been removed, as we describe in the problems box below. Look for a form plugin loading its validator on every page, two plugins loading different versions of the same library, and scripts in the header that could load in the footer. The fix for assets on the wrong pages is to wrap the enqueue in a condition:
// Checked on 16 Nov 2026, WordPress 7.1.4. Load a form script only on the contact page.
add_action( 'wp_enqueue_scripts', function () {
if ( ! is_page( 'contact' ) ) {
wp_dequeue_script( 'my-form-validator' );
}
}, 20 );Languages shows the locale and each translation file that loaded (both MO and JSON files) per text domain. If your plugin’s text domain is missing, its translation files did not load, and the usual cause is a text domain that does not match the one in the plugin header or the load_plugin_textdomain() call. The plugin documentation also has a page on JavaScript translation files for problems in block editor scripts.
What about blocks, transients, object cache and capability checks?
- Blocks: lists the blocks within post content and within full site editing, with their properties. Use it when a block renders on the front end differently than in the editor, or when attributes are not what you expect.
- Transients: shows transients updated during the request. Useful when a plugin writes a transient on every page load. Our guide to finding and deleting expired transients covers the cleanup side.
- Object Cache: shows hits, misses and a hit percentage. In our test request the data reported 344 hits and 30 misses, or 91%, with no persistent cache plugin. The official cache hit rate help page is short: it says a hit rate that is always 100% with a Memcached drop-in may be a known bug fixed in memcached-redux, and a rate stuck at 0% or 100% otherwise is worth reporting. Do not use one percentage as a target, because a first request after a cache flush will always show a low rate.
- Capability Checks: lists every
current_user_can()check with its result and arguments, which is how you find a missing role or a filtered capability. It is off by default. SetQM_ENABLE_CAPS_PANELtotrueto enable it. Older guides list it as always present, and that is no longer correct. - Multisite: appears on multisite installs and records
switch_to_blog()andrestore_current_blog()usage.
How do I debug AJAX and REST API requests with Query Monitor?
There is no REST panel and no AJAX panel, because these requests have no page to draw one on. Query Monitor instead puts the data where a developer tool can read it. For a request from a user who may view Query Monitor, the response carries X-QM-* headers. On a admin-ajax.php call with a PHP warning in the handler, our test response included:
X-QM-overview-time-taken: 0.0453
X-QM-overview-memory: 3.7 MB
X-QM-php_errors-count: 1
X-QM-php_errors-error-1: {"level":"warning","message":"Undefined variable $undefined_var","file":"wp-content/mu-plugins/t.php","line":12, ...}Open the request in the Network tab and read the response headers. The headers hold the overview and PHP errors only. For the full data on a REST request, add _envelope to the URL. Per the REST API requests documentation, the request must be authenticated as a user who can view Query Monitor, using a nonce or an Application Password. The response then contains a qm property. On our test request it held db_queries, cache, http, logger, conditionals and transients, with stack traces for queries and HTTP calls.
# Checked on 16 Nov 2026. Cookie auth needs the X-WP-Nonce header from wpApiSettings.
curl -b cookies.txt -H "X-WP-Nonce: $NONCE" \
"https://example.test/wp-json/wp/v2/posts?_envelope=1&per_page=1"We ran that pattern against a custom post type route. The envelope showed our logged messages, the failed HTTP call and every query with its time. For the error codes you see on admin-ajax.php itself, such as 400 with 0 and 403 with -1, read our guide to debugging admin-ajax.php requests.
How do I log and time my own code in Query Monitor?
Query Monitor adds a small logging and timing API that you call with do_action(), so it is safe to leave in code when the plugin is not installed: the action simply has no listeners. The profiling and logging documentation lists the levels (debug, info, notice, warning, error, critical, alert, emergency), and says messages at warning level or above also raise a notification in the toolbar.
// Checked on 16 Nov 2026, Query Monitor 4.1.1
do_action( 'qm/debug', 'Debug message from the test' );
do_action( 'qm/warning', 'Warning with context: {id}', array( 'id' => 42 ) );
do_action( 'qm/info', array( 'venue' => 'Main Hall', 'seats' => 120 ) );
do_action( 'qm/assert', 1 === 2, 'Assertion that fails' );
do_action( 'qm/start', 'my_timer' );
// ... work ...
do_action( 'qm/lap', 'my_timer' );
// ... more work ...
do_action( 'qm/stop', 'my_timer' );The four log calls above appeared in the request data as a debug entry, a warning entry with the {id} placeholder replaced by 42, an info entry that printed the array, and an error entry reading “Assertion failed: Assertion that fails”. Each entry also carried the call stack of the place that logged it. Timers show elapsed time and approximate memory in the Timing panel, and nested timers lower memory accuracy. You can also pass exceptions, WP_Error objects and other variables, but keep them small, because the data is held in memory for the request.
For code that runs very long, call do_action( 'qm/cease' ). The readme says this makes Query Monitor detach, discard what it has collected and skip its output, which is the right move for backups, large imports and security scans that would otherwise fill memory with query data.
Is it safe to leave Query Monitor active on a live site?
It is safe in the sense that its output is limited to users who hold the capability, but “safe” is not the same as “free”. The readme says it has a small effect on page generation time, and a larger effect on memory on pages with hundreds of queries, because each query carries a stack trace. The data includes file paths, queries and hook names, which you do not want in front of anyone who should not see them.
Our practical advice for production sites is to install it when you are diagnosing a problem, keep the list of administrators short, and deactivate it when you are done. If you leave it active, define QM_DISABLED in the contexts where it should not run, and review who holds view_query_monitor. Deactivating the plugin removes its db.php symlink, which is another reason to treat it as a tool you switch on.
When should I use Query Monitor instead of WP_DEBUG?
They answer different questions and work well together. WP_DEBUG and its log capture every error on every request without a plugin. Query Monitor explains one request in depth, with attribution to a plugin or theme.
Scenario | Use |
|---|---|
Which query is slow on this page? | Query Monitor, Database Queries |
Which plugin modifies this filter? | Query Monitor, Hooks & Actions |
Which request goes to an outside server? | Query Monitor, HTTP API Calls |
Capture errors from every request, including cron and CLI |
|
Keep errors off the page but still record them |
|
JavaScript errors in the browser |
|
A REST or AJAX request fails | Query Monitor headers and |
A translation is missing | Query Monitor, Languages |
Which Query Monitor add-ons are worth knowing?
The plugin’s add-on page lists these on 16 Nov 2026, with the descriptions given by their authors:
- Query Monitor Extend: lists conditionals for WooCommerce, plus many core constants and paths.
- Included Files: shows the included files for each page load with component and file size.
- bbPress and BuddyPress Conditionals, and GiveWP Conditionals: add those plugins’ functions to the Conditionals panel.
- Redis Object Cache and Object Cache Pro: provide detailed information about the Redis connection and cache usage.
- Twig Profile: shows Twig profiler output and works with Timber.
- Flamegraph: adds profiling flame graphs through the forp PHP extension.
- Yoast Test Helper and Pods: add panels for SEO metadata and Pods configuration.
- Freemius SDK plugins: any plugin using that SDK adds a Freemius panel.
Query Monitor also loads add-ons written for the Debug Bar plugin. Deactivate Debug Bar itself and those add-ons appear in Query Monitor’s menu.
What common mistakes and problems do people report with Query Monitor?
We read the plugin’s GitHub issue tracker on 16 Nov 2026. The project asks for bug reports there rather than on the WordPress.org forums. These are the recurring themes since version 4 shipped, and each link goes to the report.
- The Scripts panel seems to be missing. A report from April 2026 asked where it went in 4.x. The maintainer fixed it and the issue is closed. Scripts and Styles are separate panels now, so check both names.
- Raw data printed on the front end. After upgrading from 3.20.4, the 4.0.0 and 4.0.1 releases output raw data for logged-in admins on some sites. It was fixed in a later release. Update to the current version.
- The panel cannot be opened when the admin bar is hidden. Version 3 kept a thin strip when the toolbar was hidden. A July 2026 issue says version 4 removed it, and the maintainer said a replacement is needed. It is still open. The reply mentions a workaround: show the toolbar on the front end, open the panel, then hide it again.
- No toolbar item on a phone. A report that the admin bar link was gone on mobile was closed on 26 Oct 2026.
- “QueryMonitorData is not defined” in the console. A front-end report on 4.0.7 was closed by the maintainer because nothing in the plugin could change the situation, so look for another plugin or setting that blocks or alters its script.
- Too many redirects after two-factor login. A report from April 2026 describes a redirect loop on a site using Really Simple Security Pro with 2FA, fixed only by disabling Query Monitor by file. It is still open. Treat that combination with care on a live site.
- Another
db.phpdrop-in blocks the symlink. The official help page names several plugins that use the same file. The result is a working plugin with less query detail, and nothing in the page alerts you unless you read the Database Queries panel prompt.
Issue states change. The open and closed labels above are what we saw on 16 Nov 2026.
Questions people ask
Why is the Query Monitor toolbar not showing?
Check, in order: you are logged in as a user with view_query_monitor (an administrator on a single site); the admin bar is enabled for your profile; the page is not a full-page cache hit, since WordPress did not run; and QM_DISABLED is not set. On version 4, a hidden admin bar also hides the panel, as described above.
Does Query Monitor work with page caching?
Only on requests where WordPress runs. A cached page served before PHP loads has no Query Monitor data. Logged-in administrators usually bypass the page cache, and admin pages are not page cached, so you can still debug the uncached path. Our guide to the TTFB side of caching explains how to compare cached and uncached timing.
Does Query Monitor slow my site down?
A little. The readme calls the effect on page time negligible and says memory use grows on pages with hundreds of queries. Measure your own site with and without it, and use qm/cease for long jobs.
Can I use Query Monitor with WP-CLI?
Not as a panel. The plugin adds one command, wp qm enable, to create the db.php symlink. For command-line debugging you rely on logs and your own checks.
Why does the Capability Checks panel not exist for me?
It is switched off unless you define QM_ENABLE_CAPS_PANEL as true.
Which versions did you test?
Query Monitor 4.1.1 on WordPress 7.1.4 with PHP 8.3, MariaDB 11 and WP-CLI 2.12, on 16 Nov 2026. We could not capture panel screenshots, so interface details come from source, documentation and JSON output.
Plugins we build and run
We maintain these ourselves, which is why we can support them on your site.
- BuddyNextThe self-hosted community engine for WordPress
- BuddyXFree community theme, Pro when you outgrow it
- ReignPremium community theme. Add pieces, build anything
- JetonomyCommunity forum and Q&A for WordPress
- EventonomyEvents and RSVPs for WordPress communities
- LearnomyCourses and learning communities on WordPress
- ListoraDirectories and listings your members can browse
- SnipShareCode sharing built for developer communities
- WB Ad ManagerAd placements that turn traffic into revenue
- WP Career BoardA job board your community actually uses
- WP Sell ServicesSell services with offers, orders, and payouts
- MediaVersePhotos, video, and media albums for members
- WB GamificationPoints, badges, and rewards that keep members active
- Product RoadmapPublic roadmaps with voting your users trust



