Cache flush check results in PHP fatal error and unable to reference WP_CLI\Path class

[sc0ttkclark]

Bug Report

• Yes, I reviewed the contribution guidelines.
• Yes, more specifically, I reviewed the guidelines on how to write clear bug reports.

Describe the current, buggy behavior

When running the command wp doctor check cache-flush the result is a PHP fatal error with a missing WP_CLI\Path class not found.

Example error:

Fatal error: Uncaught Error: Class "WP_CLI\Path" not found in /usr/local/wp-cli/packages/vendor/wp-cli/doctor-command/src/Check/Cache_Flush.php:43
Stack trace:
#0 [internal function]: WP_CLI\Doctor\Check\Cache_Flush->WP_CLI\Doctor\Check\{closure}(Object(SplFileInfo))
#1 /usr/local/wp-cli/packages/vendor/wp-cli/doctor-command/src/Check/Cache_Flush.php(41): array_map(Object(Closure), Array)
#2 /usr/local/wp-cli/packages/vendor/wp-cli/doctor-command/src/Command.php(213): WP_CLI\Doctor\Check\Cache_Flush->run()
#3 [internal function]: WP_CLI\Doctor\Command->check(Array, Array)
#4 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/CommandFactory.php(100): call_user_func(Array, Array, Array)
#5 [internal function]: WP_CLI\Dispatcher\CommandFactory::WP_CLI\Dispatcher\{closure}(Array, Array)
#6 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Dispatcher/Subcommand.php(497): call_user_func(Object(Closure), Array, Array)
#7 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(470): WP_CLI\Dispatcher\Subcommand->invoke(Array, Array, Array)
#8 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(493): WP_CLI\Runner->run_command(Array, Array)
#9 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(136): WP_CLI\Runner->run_command_and_exit()
#10 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Runner.php(1228): WP_CLI\Runner->do_early_invoke('before_wp_load')
#11 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/WP_CLI/Bootstrap/LaunchRunner.php(28): WP_CLI\Runner->start()
#12 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/bootstrap.php(84): WP_CLI\Bootstrap\LaunchRunner->process(Object(WP_CLI\Bootstrap\BootstrapState))
#13 phar:///usr/local/bin/wp/vendor/wp-cli/wp-cli/php/wp-cli.php(35): WP_CLI\bootstrap()
#14 phar:///usr/local/bin/wp/php/boot-phar.php(20): include('phar:///usr/loc...')
#15 /usr/local/bin/wp(4): include('phar:///usr/loc...')
#16 {main}
  thrown in /usr/local/wp-cli/packages/vendor/wp-cli/doctor-command/src/Check/Cache_Flush.php on line 43

Describe how other contributors can replicate this bug

• Run wp doctor check cache-flush
• See PHP fatal error
• Run other checks
• No PHP fatal error shown (cache-flush check appears to be the only one using the WP_CLI\Path class).
• Run wp cli update and see no PHP fatal error about the WP_CLI\Path class, notice that it makes it past the usage of the class method

Describe what you would expect as the correct outcome

Path class should exist and be loaded like the other WP_CLI namespace classes.

Let us know what environment you are running this on

OS:     Linux 6.12.0-211.22.1.el10_2.x86_64 #1 SMP PREEMPT_DYNAMIC Thu Jun 11 08:11:48 EDT 2026 x86_64
Shell:
PHP binary:     /usr/local/bin/php
PHP version:    8.2.30
php.ini used:   /usr/local/etc/php/php.ini
MySQL binary:   /usr/bin/mysql
MySQL version:  mysql  Ver 8.4.8-8 for Linux on x86_64 (Percona Server (GPL), Release '8', Revision '1c288264')
SQL modes:
WP-CLI root dir:        phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:      phar://wp-cli.phar/vendor
WP_CLI phar path:       phar:///usr/local/bin/wp
WP-CLI packages dir:    /usr/local/wp-cli/packages/
WP-CLI cache dir:       /root/.wp-cli/cache
WP-CLI global config:
WP-CLI project config:
WP-CLI version: 2.12.0

Provide additional context/Screenshots

Here are some things I noticed:

• WP_CLI\Path is only actively called by the cache flush check, the only other place in this repo that references it seems to be uncalled by anything else
• WP_CLI\Path can be used just fine when calling wp cli update which seems to prove the class can be autoloaded and used by the primary WP-CLI phar

[sc0ttkclark]

I've tried this locally and on a hosting platform I was testing on and both have the same PHP fatal.

Here's the local wp cli info:

OS:	Darwin 25.5.0 Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:15 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6041 arm64
Shell:	/bin/zsh
PHP binary:	/Users/XXXXXX/Library/Application Support/Local/lightning-services/php-8.4.18+1/bin/darwin-arm64/bin/php
PHP version:	8.4.18
php.ini used:	/Users/XXXXXX/Library/Application Support/Local/run/vhEeAuGdM/conf/php/php.ini
MySQL binary:	/Users/XXXXXX/Library/Application Support/Local/lightning-services/mysql-8.0.35+4/bin/darwin-arm64/bin/mysql
MySQL version:	mysql  Ver 8.0.35 for macos13 on arm64 (MySQL Community Server - GPL)
SQL modes:	
WP-CLI root dir:	phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:	phar://wp-cli.phar/vendor
WP_CLI phar path:	phar:///Applications/Local.app/Contents/Resources/extraResources/bin/wp-cli/wp-cli.phar
WP-CLI packages dir:	/Users/XXXXXX/.wp-cli/packages/
WP-CLI cache dir:	/Users/XXXXXX/.wp-cli/cache
WP-CLI global config:	/Applications/Local.app/Contents/Resources/extraResources/bin/wp-cli/config.yaml
WP-CLI project config:	
WP-CLI version:	2.12.0

[swissspidy]

Thanks for your report! Looks like we forgot to raise the version requirements here for wp-cli/wp-cli. Meanwhile you can fix this with wp cli update --nightly

[sc0ttkclark]

@swissspidy I don't see a WP-CLI 2.13 version tagged or released, is that the right version? I see that the main branch is currently set in https://github.com/wp-cli/wp-cli/blob/main/VERSION as 2.13.0-alpha but it wasn't clear to me the 2.13 plan since the only open milestone on GitHub is currently the 3.0.0 one https://github.com/wp-cli/wp-cli/milestones

Is it correct that to run the doctor command as of the upcoming v2.3.2 version -- you will need to be running a nightly unreleased version of WP-CLI?

For context, I'm trying to avoid headaches if you release v2.3.2 and it suddenly starts requiring a newer version of WP-CLI than we require (currently we have v2.12.0 required) in our build steps on hosting infrastructure for the PHP images we use.

[swissspidy]

Is it correct that to run the doctor command as of the upcoming v2.3.2 version -- you will need to be running a nightly unreleased version of WP-CLI?

Yes. Stable release should be hopefully out soon though.

Meanwhile you can pin to an older version of this package.

[swissspidy]

Closing for now as fixed in #214