Skip to content
WordPress Maintenance

When WP-CLI fatals on the plugin you came to rescue

A WordPress plugin update breaks the site. You SSH in to roll back the bad plugin with WP-CLI, and you get this:

Fatal error: Uncaught Error: ... in /path/to/broken-plugin/main.php:42

The plugin you came to fix has now stopped the tool you came to fix it with. It looks contradictory, but it makes sense once you know how WP-CLI starts up — and there’s a flag pair that gets you out.

Why WP-CLI itself crashes

When you run a rollback command like wp plugin install <name> --version=X --force, WP-CLI internally boots WordPress before doing anything else. Plugin registration and option loading all happen during WordPress’s startup, so a broken plugin gets loaded there, throws a fatal, and takes the WP-CLI process down with it.

The sequence:

  1. WP-CLI boots WordPress
  2. WordPress loads the active plugins
  3. The broken plugin throws a fatal
  4. WP-CLI exits before ever reaching the file-replace step

The actual rollback (downloading the PHAR, overwriting the plugin directory) never gets a chance to run.

The fix — safe-mode flags

WP-CLI has two startup flags, --skip-plugins and --skip-themes. With both set, WordPress’s startup skips loading any plugins and themes at all.

wp plugin install <name> --version=X --force --skip-plugins --skip-themes

File-system operations (downloading the PHAR, unpacking it, replacing files) don’t depend on plugin code, so they run fine. The broken plugin never gets loaded at boot, so it never fatals, and the rollback completes.

Should you set these flags everywhere?

You might think “why not just add these to every WP-CLI command by default?” But some commands genuinely need plugins or themes loaded. wp cache flush relies on the object-cache plugin’s hooks. wp doctor reads diagnostic information that plugins register. Setting safe-mode flags on those would break them in subtle ways.

The practical split: file-operation commands always get --skip-plugins --skip-themes. Cache and diagnostic commands don’t.

That single rule eliminates the worst-case “WP-CLI doesn’t work when you need it most” scenario from the maintenance workflow. For anyone running WP-CLI–based automation, this is a flag pair worth committing to muscle memory.