WP-CLI Doctor Command: An Essential Tool for WordPress Troubleshooting

Content Error or Suggest an Edit

Notice a grammatical error or technical inaccuracy? Let us know; we will give you credit!

Draft Warning

You’ve reached a draft 🤷‍♂️ and unfortunately, it’s a work in progress.


The WP-CLI Doctor Command is a powerful tool that helps diagnose and troubleshoot issues with your WordPress site. It performs a series of checks and offers recommendations to help you identify and resolve problems, including outdated plugins and themes, server configuration issues, and more. In this article, we’ll explore the Doctor Command in detail and show you how to use it to keep your WordPress site running smoothly.

What is the WP-CLI Doctor?

The WP-CLI Doctor Command (WordPress Command Line Interface) command checks your WordPress installation for common problems and issues. It is designed to help you diagnose and troubleshoot issues with your site quickly and easily without having to go through the hassle of manually inspecting every aspect of your site.

GitHub – wp-cli/doctor-command: Diagnose problems within WordPress by running a series of checks for symptoms
Diagnose problems within WordPress by running a series of checks for symptoms – GitHub – wp-cli/doctor-command: Diagnose problems within WordPress by running a series of checks for symptoms

How to Install the WP-CLI Doctor?

Before you can use the WP-CLI Doctor Command, you need to install WP-CLI on your system. To install WP-CLI, you’ll need access to your server’s command line. Once you’ve installed WP-CLI, you can install the Doctor Command by running the following command:

wp package install wp-cli/doctor-command:@stable

How to Use the WP-CLI Doctor?

To use the WP-CLI Doctor Command, navigate to your WordPress installation directory using the command line and run the following command:

wp doctor check

This will run a series of checks on your site, including WordPress core files, plugins, themes, server configuration, and more. The Doctor Command will then provide a report of any issues it finds, along with recommendations for how to resolve them.

What Checks Does the WP-CLI Doctor Perform?

The WP-CLI Doctor Command performs a wide range of checks on your WordPress installation, including:

  • WordPress core files: Check that all WordPress core files are up-to-date and have not been modified.
  • Plugins and themes: Check that all plugins and themes are up-to-date, compatible with your version of WordPress, and have not been modified.
  • PHP and server configuration: Check that your PHP and server configuration meet the minimum requirements for running WordPress.
  • Database: Check that your WordPress database is up-to-date and functioning correctly.
  • Security: Checks for common security issues, such as weak passwords and outdated encryption protocols.
  • Performance: Checks for issues like slow page load times and excessive server load.

WP-CLI Doctor Checks

The full list of available checks is listed on the wp-cli website below.

Default doctor diagnostic checks – WP-CLI – WordPress.org
Check CommandShort DescriptionLong Description
autoload-options-sizeAutoload Options Size CheckWarns when the size of the autoloaded options exceeds the threshold of 900 kb.
constant-savequeries-falsySave Queries Constant CheckConfirms the expected state of the SAVEQUERIES constant.
constant-wp-debug-falsyWP Debug Constant CheckConfirms the expected state of the WP_DEBUG constant.
core-updateWordPress Core Update CheckErrors when a new WordPress minor release is available; warns for a major release.
core-verify-checksumsWordPress Core Verify ChecksumsVerifies WordPress files against published checksums and errors on failure.
cron-countCron Count CheckErrors when there are more than 50 total cron jobs registered.
cron-duplicatesDuplicate Cron Jobs CheckErrors when there are more than 10 duplicate cron jobs registered.
file-evalFilesystem Eval CheckChecks files on the filesystem for the regex pattern `eval(.*base64_decode(.*`.
option-blog-publicBlog Public Option CheckConfirms the expected value of the 'blog_public' option.
plugin-active-countActive Plugins Count CheckWarns when there are more than 80 active plugins.
plugin-deactivatedDeactivated Plugins CheckWarns when more than 40% of the installed plugins are deactivated.
plugin-updatePlugin Updates CheckWarns when there are plugin updates available.
theme-updateTheme Updates CheckWarns when there are theme updates available.
cache-flushCache Flush CheckDetects any use of the `wp_cache_flush()` function.
php-in-uploadPHP in Uploads Folder CheckWarns when a PHP file is present in the Uploads folder.
language-updateLanguage Updates CheckWarns when there are language updates available.

Handling WP-CLI Doctor Errors

php-in-upload – PHP files detected in the Uploads folder.

There is PHP files located in the wp-content/uploads folder. You can find any file named .php by running the following command in your wp-content/uploads directory.

find . -type f -name "*.php"

    Common Issues with WP-CLI Doctor

    Below are some common issues you might face using the wp-cli doctor command.

    Error: YIKES! It looks like you’re running this as root.

    This error will appear if you’re running wp-cli as root. It’s suggested that you don’t run wp-cli as root for a number of security reasons. If you are aware of the implications of running wp-cli as root, you can simply add –allow-root to your wp-cli command

    wp --allow-root doctor checks --all

    Troubleshooting Errors when Running All Checks

    You might find that when you run all of the wp-cli doctor checks (wp doctor checks --all) that an error will occur. It might be one of the errors below, or it might not. The easiest way to troubleshoot the issue is to run each check individually. You can do this two ways: manually run them one by one or use the following bash one-liner.

    Bash one-liner

    for cmd in "autoload-options-size" "constant-savequeries-falsy" "constant-wp-debug-falsy" "core-update" "core-verify-checksums" "cron-count" "cron-duplicates" "file-eval" "option-blog-public" "plugin-active-count" "plugin-deactivated" "plugin-update" "theme-update" "cache-flush" "php-in-upload" "language-update"; do wp doctor check "$cmd"; done

    Bash one-liner with –allow-root –skip-themes –skip-plugins

    for cmd in "autoload-options-size" "constant-savequeries-falsy" "constant-wp-debug-falsy" "core-update" "core-verify-checksums" "cron-count" "cron-duplicates" "file-eval" "option-blog-public" "plugin-active-count" "plugin-deactivated" "plugin-update" "theme-update" "cache-flush" "php-in-upload" "language-update"; do if ! wp doctor --allow-root --skip-themes --skip-plugins check $cmd | grep -q 'Success'; then echo "Error detected in $cmd:"; wp doctor "$cmd"; fi; done && echo "All checks completed successfully"

    Full Bash Script

    Here’s a full bash script that is easier on the eyes.

    # Loop through each doctor command and check for errors
    for cmd in "${commands[@]}"
        wp doctor check "$cmd" 

    Error: There has been a critical error on this website.

    When running a check, you may receive the following error, typically due to a plugin or theme. You can skip all plugins and themes by issuing the following command.

    wp --skip-themes --skip-plugins

    This doesn’t change how the doctor command operates.

    PHP Fatal error: Allowed memory size

    You might find that when running the wp-cli doctor command, you’ll receive an error message about “Allowed memory size bytes exhausted”.

    Running checks 12 % [===================> ] 0:14 / 2:00
    PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 184876416 bytes) in .wp-cli/packages/vendor/wp-cli/doctor-command/inc/checks/class-file-contents.php on line 64

    There are a couple of reasons for this error.

    PHP CLI Memory Limit Exhausted

    The PHP CLI command is governed by its own php.ini and might have a different memory limit size. If you want to know the memory limit for PHP CLI, you can run the following command.

    wp eval "echo ini_get('memory_limit');" --skip-wordpress

    If you wish to change the memory_limit size, you can see which php.ini memory_limit that wp-cli has by running the command wp --info

    wp --info
    OS:     Linux 4.15.0-208-generic #220-Ubuntu SMP Mon Mar 20 14:27:01 UTC 2023 x86_64
    Shell:  /bin/bash
    PHP binary:     /usr/local/lsws/lsphp80/bin/php
    PHP version:    8.0.26
    php.ini used:   /usr/local/lsws/lsphp80/etc/php/8.0/litespeed/php.ini
    MySQL binary:   /usr/bin/mysql
    MySQL version:  mysql  Ver 15.1 Distrib 10.5.18-MariaDB, for debian-linux-gnu (x86_64) using readline 5.2
    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:       /root
    WP-CLI packages dir:    /root/.wp-cli/packages/
    WP-CLI cache dir:       /root/.wp-cli/cache
    WP-CLI global config:
    WP-CLI project config:
    WP-CLI version: 2.7.1

    You can see that the wp-cli command is using the php.ini file at /usr/local/lsws/lsphp80/etc/php/8.0/litespeed/php.ini and you can change the memory_limit in this file.

    mmap() failed: [12] Cannot allocate memory when running check cache-flush

    The check “cache-flush” has issues when the wp-content folder has many files; the affected site had 40,000 files in the wp-content directory. I’ve filed a bug on the doctor-command Github.

    mmap() failed: [12] Cannot allocate memory when running check cache-flush · Issue #178 · wp-cli/doctor-command · GitHub
    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 The check “cache-flush” has issues when the wp-content fold…


    The WP-CLI Doctor Command is an essential tool for anyone who manages a WordPress site. It helps you quickly identify and resolve issues, ensuring your site runs smoothly and securely. With its wide range of checks and recommendations, the Doctor Command makes troubleshooting your WordPress site easier.


    You May Also Like
    Read More

    Why should you use sudo?

    Introduction There was a question on the popular GridPane Facebook Group asking about login in as the system…

    GridPane Releases Limited API

    GridPane API Documentation GridPane released an API, with limited functionality. You can review the API document here. https://documenter.getpostman.com/view/13664964/TVssjU7Z…