"Unable to run PHP in command line mode" error when running remote MODX upgrade

When running a remote MODX upgrade, you may encounter one of these errors:

  • Unable to run PHP in command line mode, `php --version` returned version number "5.5.2" which is either invalid or below the minimum required to install MODX.
  • Unable to run PHP in command line mode, `php --version` did not return valid output.

These are part of the pre-installation checks to make sure your server can execute PHP code in command line (CLI) mode. This is necessary for the final step of the remote upgrade, which runs the MODX setup in command line mode.

Both errors are caused by (invalid) configuration on the server, although the specific cause and fix for them are slightly different.

Invalid or too low PHP version

If this error does provide a PHP version number, it means SiteDash was successfully able to instruct your server to run PHP code in CLI mode, however the installed command line version of PHP is too low to continue. 

This can happen if the PHP version for your front-end webserver is different from the one on the command line, and the latter hasn't been updated in a while. As MODX 2.x requires at least PHP 5.6 to run the installation successfully, we check the command line version of PHP before continuing with the setup. For MODX 3, at least PHP 7.2 is required.

To resolve this, we recommend talking to your host or server administrator. Mosts hosts are happy to resolve this, and in some cases server control panels offer you the ability to change the "global" PHP version through a PHP version selector, which typically affects the command line version.

If the error message does not provide a PHP version number in the quotes, you've run into an edge case we didn't think was possible. Please get in touch with support, providing your site's domain name and/or site key so we can investigate further.

Did not return valid output

If the PHP version check did not return valid output, that means something else is afoot. Where we've seen this, typically the attempt to run PHP in command line mode is being interpreted by the server as a web request. That breaks the version check and will also prevent the setup from completing. 

One reason this seems to happen is if the server is configured with PHP-FPM and "cgi-fcgi" for the webserver, and requires a different executable to be used on the command line. SiteDash will automatically identify the used executable for the web request and fail to recognise there's a different CLI version. 

Note that this does not affect all PHP-FPM setups; remotely upgrading MODX on servers running nginx and PHP-FPM works fine for the vast majority of our users out of the box.

Fix: tell SiteDash which PHP executable to use

Both cases can usually be fixed by changing the PHP executable SiteDash uses. This is done by changing the sitedashclient.php_binary system setting, to instruct a specific executable to be used.

Go to System > System Settings in your sites' manager, and find the sitedashclient.php_binary system setting. Set the value to the absolute path including binary name.

  • On Variomedia servers use: /vrmd/webserver/php74/bin/php-cli
  • On Strato servers use: /opt/RZphp74/bin/php-cli
  • On IONOS servers use: /usr/bin/php7.4-cli

On other servers, ask the host or server administrator what the right PHP executable is. Or if you have SSH access, you can find out yourself by connecting and running php --version. if that gives the expected version output, run which php and use the path returned from that.

This only has to be done once, but may need to be adjusted if you move servers at some point in the future.

Still need help? Send us an email Send us an email