A WordPress Plugin Stopped Working: The Debug Order That Finds It

When a WordPress plugin stops working, turn on WP_DEBUG_LOG and read the error before you touch anything else. Most people start by deactivating plugins one at a time, which works eventually and wastes an hour. The log usually names the file and line in about ninety seconds.

Plugin failures come in a small number of shapes, and each shape has a fast diagnostic. The mistake is treating them all as the same mystery and reaching for the same brute-force bisect every time. Here is the order that finds the cause fastest, from cheapest check to most expensive.

Step one: turn on the log and read it
Step two: is it PHP, JavaScript, or the network?
Step three: isolate the conflict, without breaking the live site
The failures that are not plugin bugs at all
Recovering when the admin is locked out
Making the next one faster
How this fits the rest of the stack
FAQ

Step one: turn on the log and read it

WordPress writes nothing useful by default. The first move on any plugin problem is to change that.

// wp-config.php -- above the "That's all, stop editing" line
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );   // writes wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // do NOT print to the page
@ini_set( 'display_errors', 0 );

// Also useful when the admin looks stale after a plugin update
define( 'SCRIPT_DEBUG', true );

WP_DEBUG_DISPLAY must be false on anything public. Printing errors to the page leaks file paths and sometimes credentials. The log file is the target, not the screen.

Reproduce the problem, then read the tail of the log:

tail -n 100 wp-content/debug.log

# Or watch it live while you click
tail -f wp-content/debug.log

A fatal error names the file, the line, and usually the plugin directory. That is the answer, and you got it without deactivating anything. Deprecation notices and warnings are noisier but still point at the offending code.

If debug.log is empty after reproducing, the failure is not PHP — it is JavaScript, a permission, or a request that never reached WordPress. Move to the next step.

Step two: is it PHP, JavaScript, or the network?

Open DevTools before touching plugins. The browser answers a question the server log cannot.

Console errors — a JavaScript exception in the plugin’s script, or a jQuery conflict. Very common after a WordPress core update changes a bundled library version.
Failed network requests — a 403 on admin-ajax.php is usually a nonce or capability problem. A 500 is PHP, and now you know to go back to the log. A 404 on a REST route means permalinks need flushing.
Blocked mixed content — the plugin is loading an asset over HTTP on an HTTPS page, and the browser refuses it silently apart from a console line.

The single most common plugin symptom — a settings page where the Save button does nothing — is almost always one of these three, and almost never a plugin conflict. Checking the console first saves the whole bisect.

A quick sanity check for the permalink case, which is disproportionately common after any plugin that registers routes or post types:

wp rewrite flush --hard

# Or in the admin: Settings -> Permalinks -> Save Changes
# (Saving with no edits is enough; it rebuilds the rules.)

Step three: isolate the conflict, without breaking the live site

If the log and the console are both clean, you are in conflict territory. Do not start deactivating plugins on a production site — use the built-in tool that scopes the deactivation to your session only.

Install the Health Check and Troubleshooting plugin, then enable Troubleshooting Mode. It deactivates all plugins and switches to a default theme for your session only. Visitors see the site unchanged.

From there the bisect is standard and should be binary, not linear:

Confirm the problem disappears with everything off. If it does not, the plugin is not the cause — look at the theme, then at the host.
Re-enable half the plugins. Test.
Whichever half reproduces it, halve again. Test.
Repeat. Twenty plugins resolve in about five checks rather than twenty.

Once you have the pair, the conflict is usually one of a small set: two plugins enqueueing different versions of the same library, two registering the same shortcode or REST namespace, or one calling wp_die() inside a hook the other depends on.

The failures that are not plugin bugs at all

A meaningful share of plugin problems are environmental. These are worth checking early because they are quick and they explain the cases where nothing in the code looks wrong.

PHP version mismatch. A plugin using match or enums needs PHP 8. On PHP 7.4 it fatals on parse, often with a blank screen and nothing in the log because the file never compiled.
Memory limit. A plugin that works on a small site and dies on a large one is usually hitting memory_limit. The log says Allowed memory size of N bytes exhausted.
Execution timeout. Import and migration plugins hit max_execution_time and die mid-run, leaving partial state. The fix is WP-CLI, not a bigger timeout.
File permissions. A plugin that cannot write to wp-content/uploads fails in ways that look like feature bugs.
Blocked outbound requests. Licence checks and API calls fail if the host blocks outbound HTTP. WP_HTTP_BLOCK_EXTERNAL in wp-config.php does this deliberately and is easy to forget.

Check the versions first, since it costs one command:

wp cli info
wp plugin list --status=active --fields=name,version,update
php -v

Recovering when the admin is locked out

The worst case: a plugin fatals hard enough that /wp-admin is unreachable, so you cannot deactivate it through the UI. This is a five-minute problem if you have file access and an afternoon if you do not.

The reliable fix is to rename the plugin’s directory. WordPress cannot load a plugin whose folder has moved, so it deactivates it and lets you back in.

# Via SSH or a file manager
mv wp-content/plugins/broken-plugin wp-content/plugins/broken-plugin.off

# Or with WP-CLI, which still works when the admin does not
wp plugin deactivate broken-plugin

# Nuclear option -- deactivate everything, then re-enable selectively
wp plugin deactivate --all

WP-CLI works when the browser admin is down, because it bypasses the request lifecycle that is failing. That alone is a good reason to have shell access to a WordPress install.

If you have neither shell nor a file manager, the last resort is the database: set the active_plugins option to an empty serialised array. It works, and it is unpleasant enough that it is worth choosing hosting where you do not have to.

Making the next one faster

Most of the time cost in plugin debugging is access friction — finding credentials, waiting on an FTP client, hunting for where the log went. The debugging itself is quick once you can see.

Managed WordPress on RunxBuild puts a file manager and a database browser in the dashboard, so renaming a plugin directory or reading debug.log is a click rather than a session. Runtime logs are in the same place, which means the fatal error and the request that caused it are on one screen. The WordPress files documentation covers what the file manager reaches.

Two habits worth more than any tool. Update plugins one at a time on a site that matters, so a break has exactly one candidate cause. And keep a staging copy — the freedom to break something completely is what makes the binary bisect fast, and you cannot bisect freely on production.

How this fits the rest of the stack

The order is what saves the time: log, then browser console, then a scoped conflict bisect, then environment. Most plugin failures resolve at step one or two, and the hour-long deactivation ritual is usually skipped entirely. If you are looking at WordPress hosting where the logs, files, and database are all reachable without an FTP client, the RunxBuild hosting calculator shows what the plan and the database cost separately.

Useful related references:

FAQ

How do I see WordPress plugin errors?

Set WP_DEBUG and WP_DEBUG_LOG to true in wp-config.php, and WP_DEBUG_DISPLAY to false. Reproduce the problem, then read wp-content/debug.log. A fatal error names the file, line, and usually the plugin.

How do I find which plugin is causing a conflict?

Use the Health Check and Troubleshooting plugin’s Troubleshooting Mode, which deactivates plugins for your session only so visitors are unaffected. Then bisect — re-enable half at a time rather than one at a time.

What do I do if a plugin locks me out of wp-admin?

Rename the plugin’s folder in wp-content/plugins via SSH or a file manager. WordPress cannot load a plugin whose directory has moved, so it deactivates it. WP-CLI’s wp plugin deactivate also works when the admin does not.

Why does a plugin work on one site and not another?

Usually environment rather than code — a different PHP version, a lower memory limit, a shorter execution timeout, stricter file permissions, or blocked outbound HTTP requests. Check wp cli info and php -v before assuming a bug.

Is it safe to deactivate plugins on a live site to debug?

Not with the normal deactivate button, which affects every visitor. Troubleshooting Mode scopes the deactivation to your own session, so the live site keeps working while you bisect.