Description
The usual way to find a plugin conflict is to deactivate plugins one at a time and see what changes. On a live site that means taking features away from real visitors and customers while you experiment.
TroubleLens does the same investigation without that cost. It gives you a private troubleshooting session: plugins you switch off stop loading for your requests only. Everyone else — visitors, customers, other administrators, search engines, scheduled tasks — continues to get the site exactly as it is. The list of active plugins in your database is never changed.
How it works
Starting a session writes one small must-use plugin and sets a cookie in your browser. On requests carrying that cookie, WordPress is told a different list of active plugins. That is the only supported way to do this: the plugin list is read before any normal plugin has loaded, so the code doing the filtering has to already be running.
What it does
- Troubleshooting mode. Switch any active plugin off for yourself. Nothing is deactivated.
- Theme test. Render your own session with a bundled default theme while visitors keep the live one.
- Guided isolation. Answer “is the problem still there?” a handful of times and the plugin narrows twenty candidates down to one by halves, then confirms it by switching that one off and on again.
- Diagnostics. REST API, WP-Cron and read-only database checks, plus errors read from the WordPress debug log and grouped by the component they were recorded in.
- WooCommerce checks. Version, required pages, HTTPS, template overrides that have fallen behind, and the scheduled action queue. Only appears when WooCommerce is running.
- Support report. Everything gathered, in text or JSON, with credentials and personal data stripped out.
- Automatic isolation. Describe how to tell the problem apart once and the whole search runs itself, fetching the page through your session after each round.
- JavaScript errors. Recorded in your browser during a session and attributed to a plugin or theme. These never reach the PHP debug log.
- Duplicate libraries. Two copies of jQuery or Select2 on one page, named with both loaders. Found without reproducing anything.
- Where plugins meet. Hooks with callbacks from more than one plugin, and which plugins detach other people’s callbacks.
- Load cost. What each plugin adds to a page, measured by switching it off for your session and reloading.
- What changed. Real version numbers recorded when WordPress updates something, so “it worked yesterday” has an answer.
What it will not do
This is a diagnostic tool, so it does not change things it is measuring:
- It never writes to the
active_pluginsoption, and it prevents anything else from writing it while a session is running. - It never switches your real theme.
- It never deletes, optimises or repairs anything in the database, and never clears a transient or a scheduled event.
- It never writes to
wp-config.php, including to enableWP_DEBUG. - It never installs its own PHP error handler. It reads what WordPress already records, and states plainly what that misses.
- It never reports a plugin as the cause of anything. It reports what was observed, with the observations attached, and says “strong candidate” where that is what the evidence supports.
Privacy
TroubleLens has no telemetry, no tracking and no advertising, and contacts no third party service. The HTTP requests it makes go to your own site and nowhere else: to your REST API, to check that it answers, and to your own pages, to time them or to see whether a symptom is still there.
There are exactly two exceptions, and each only happens when you press the button that causes it.
The outgoing mail check sends a single message to the email address on your own account, so that a site whose mail is broken finds out before its customers do. It carries nothing about your site beyond its name.
The core file check asks WordPress.org for the list of checksums published for your exact version, and compares the files here against it. All it sends is the version and language needed to identify which list to return. Your own themes, plugins and uploads are never checked, because nobody publishes checksums for those.
Support reports are built and rendered on your server. Nothing is transmitted anywhere; you copy or download the report and send it yourself. Before it is shown to you, passwords, salts, authentication keys, tokens, API keys and payment gateway credentials are removed, email addresses are replaced, and absolute server paths are made relative.
Screenshots
Installation
- Upload the plugin through Plugins Add Plugin Upload Plugin, or install it from the plugin directory.
- Activate it.
- Open TroubleLens in the admin menu.
Activation writes nothing beyond a version marker. The must-use file that makes troubleshooting sessions work is only written when you start your first session, and is removed again when you deactivate the plugin.
FAQ
-
Will my visitors notice anything?
-
No. A troubleshooting session applies to requests that carry your session cookie. Every other request — every visitor, bot, cron run and other logged-in user — loads the site normally.
-
Can I break my site with this?
-
The session only affects you, so a mistake stays with you. If you switch off something your admin screens need, the recovery link on the troubleshooting screen ends the session before any plugin loads, so it works even when the site is returning a fatal error.
-
How do I get out if everything is broken?
-
In order of how little needs to be working: use the recovery link shown on the troubleshooting screen; clear this site’s cookies in your browser; wait for the session to expire; add
define( 'TROUBLELENS_DISABLE', true );towp-config.php; or deletewp-content/mu-plugins/troublelens-conflict-detector-loader.php. Deactivating the plugin does the last two for you. -
Can I browse the site logged out while a session is running?
-
No. The session is tied to your user account, and a request that is not you ends it. This is deliberate: it is what stops a leaked cookie applying to anybody else.
-
Why can’t I switch off a must-use plugin?
-
Must-use plugins load before any code that could filter them, including this one. The same is true of drop-ins like
object-cache.php. The overview screen lists them so you know what is outside the test. -
Why did switching off one plugin switch off others?
-
Because they declare that they require it. WordPress deactivates dependents when a dependency goes, and a session does the same, or those plugins would be running against something that is not there — producing an error that looks exactly like the conflict you are hunting. The screen tells you which ones went and why.
-
Why can’t I deactivate a plugin while a session is running?
-
You can deactivate a plugin you have not hidden. What is blocked is a plugin deactivating itself, which many do when a dependency is missing. Without that block, hiding WooCommerce for your own session would make its extensions switch themselves off for every visitor.
-
Does it work on multisite?
-
On multisite, only network administrators can start a session, and only the current site’s own active plugins can be switched off. Network-activated plugins are listed and flagged but cannot be toggled.
-
Where do the error reports come from?
-
From the WordPress debug log, when
WP_DEBUG_LOGis enabled, and from the extensions WordPress itself paused after catching a fatal error. The plugin will not enable debugging for you, because that means editingwp-config.php. The diagnostics screen lists exactly what this approach cannot see. -
Built to be extended
-
The screens, the diagnostics, the findings and the report are all open to a plugin that wants to add to them, through documented filters and actions with tests that prove each one fires. Whatever an add-on contributes to a report is redacted along with everything else, and a finding it adds carries the observations behind it like any other. See docs/EXTENDING.md in the plugin folder.
-
Credits
-
The icons and the two illustrations in this plugin were generated with AI rather than taken from an icon set, so nothing here carries a third party licence. They are distributed under the same GPLv2 or later as the rest of the plugin.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“TroubleLens – Conflict Detector” is open source software. The following people have contributed to this plugin.
Contributors
Translate “TroubleLens – Conflict Detector” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.0.1
Changes made during the WordPress.org review, before the first public release.
- Renamed to TroubleLens. The previous name was close enough to an existing project’s terminology to be a problem, and the reviewer asked for a distinctive one.
- A fatal error during your session is now recorded and reported. Previously a request that died took the screen with it and left nothing to read, which is the situation people most often open this plugin for.
- Added a How to use section: the four steps, what each other section is for, and what a clean result does not prove.
- Every value read from a request is now sanitized where it is read.
1.0.0
First release.
Troubleshooting:
- Per-administrator troubleshooting sessions that never alter the active plugin list. Visitors, customers, other administrators, search engines and scheduled tasks all continue to see the site as it is.
- Dependency-aware switching, so hiding a plugin also hides whatever requires it.
- Protection against anything persisting the filtered plugin list, including plugins that deactivate themselves when a dependency is missing.
- Theme testing against a bundled default theme, for your session only.
- Session options: bypass the page cache, keep the admin bar on the front end, and log what the session switches off.
- The Plugins screen stops offering an Activate link for a plugin your session is hiding.
Finding the cause:
- Guided isolation by binary search, with a three-step confirmation round.
- Automatic isolation: describe the symptom once and the search runs itself, with no questions to answer.
- Evidence bands rather than invented percentages, always shown with the observations behind them.
- JavaScript error capture during a session, attributed to the plugin or theme whose file threw.
- Duplicate library detection: finds two copies of jQuery, Select2 and similar on one page, and names both loaders.
- Hook inspection: which plugins share a hook, and which ones call remove_action on callbacks they do not own.
- Per-plugin load cost, measured by difference and reported with a noise floor rather than as false precision.
- Update guard: records real plugin versions when WordPress updates something, rather than guessing from file dates.
Diagnostics:
- REST API, WP-Cron and read-only database checks.
- Environment checks: memory, execution time, upload limits, form field limits, PHP extensions, permalinks, character set, caching, and whether the folders this plugin needs are writable.
- PHP errors read from the debug log and from core’s paused extensions, grouped by component.
- Outgoing HTTP requests recorded during a session, with the host, how long each took and which plugin asked. A plugin waiting on somebody else’s server shows up nowhere else.
- A core file check, on a button. Compares the WordPress files here against the checksums WordPress.org published for your exact version, which is the one thing that explains behaviour surviving every plugin being switched off.
- An outgoing mail check, on a button. It sends one message to your own address and reports what WordPress said about it. This is the only thing in the plugin that leaves the site, and it never happens on its own.
- Optional WooCommerce checks: pages, HTTPS, template overrides and the scheduled action queue.
Reporting:
- Support report in text and JSON, sanitised of credentials, personal data and server paths.