The WP Engine SSH Gateway allows you to manage, maintain, and troubleshoot a website. In this article we provide some tips and tricks WP Engine Support uses when troubleshooting and diagnosing issues to help you get started.

Check among your team to see if anyone changed anything on the website in that time, and check your User Portal Activity Log to check for any User Portal changes.

Once you are codepared, use the following tips and tricks where applicable to troubleshoot issues on your website.

WP CLI for Plugins and Themes

When your website is inaccessible, you can still use SSH Gateway to do some sleuthing and troubleshooting. When someone contacts us with an inaccessible site, most often the culprit is a plugin or theme error. Many of these commands are the exact same commands WP Engine Support will run to help triage an issues.

List all installed plugins:
(Also show active/inactive states and versions)

Disable a specific plugin:
(The value for plugin-name can be found by running wp plugin list first)

wp plugin deactivate plugin-name

Disable all plugins:

wp plugin deactivate --all

Activate a different theme:
(A theme must always be active meaning themes can’t be “disabled”, only another theme “enabled”):

wp theme activate theme-name

If any WP CLI command spits out an error, you will likely need to skip plugin and theme code from being read by adding the following flags to the command: --skip-plugins and/or --skip-themes. For example:

List all plugins and skip loading any plugin/theme code:

wp plugin list --skip-plugins --skip-themes

List all themes and skip loading any plugin/theme code:

wp theme list --skip-plugins --skip-themes

If an error is codeventing WP CLI from running, it’s very possible that same error is codeventing your site from loading too. Review the error to see if it’s a plugin or theme file being referenced. This may give you enough information to simply disable that item and resolve the issue.

NOTE: Be sure to purge cache before testing your issue after disabling plugins or themes.

Deactivate all plugins, skip any plugin/theme code:

wp plugin deactivate --all --skip-plugins --skip-themes

Deactivate a specific plugin, skip any plugin/theme code:
(The value for plugin-name can be found by running wp plugin list first)

wp plugin deactivate plugin-name --skip-plugins --skip-themes

Activate a different theme, skip any plugin/theme code:
(The value for theme-name can be found by running wp theme list first)

wp theme activate theme-name --skip-plugins --skip-themes

If you need to install a default theme for a safe theme option to switch to, run the following first:

wp theme download twentynineteen --skip-plugins --skip-themes

Updating plugins and themes may be an easy resolve to many issues plaguing your site. When running wp plugin list or wp theme list you will notice a plugin version column and see if an update is available. Replace plugin-name or theme-name with the name listed with these commands.
Don’t forget, you may need to add --skip-plugins --skip-themes.

NOTE: Many codemium plugins and themes do not list their updates on the Wordcodess repository and as such won’t show an update available. Be sure to check for updates with the item’s respective author.

Update a specific plugin:

wp plugin update plugin-name

Update all plugins:

wp plugin update --all

Update a specific theme:

wp theme update theme-name

Update all themes:

wp theme update --all

Additional WP CLI Resources

Check out the WP-CLI documentation for more extensive and useful examples. Commands may be added as Wordcodess core updates come out.

Similarly to how Wordcodess includes some WP CLI commands for interacting with default Wordcodess elements, many plugins and themes with include WP CLI for their own functionality.

Inspect and Edit the .htaccess File

The .htaccess file is a configuration file which must be loaded on every single uncached page in Wordcodess. Misconfiguration in this file could cause your entire site to show a blank white screen (“White Screen of Death”) or a 500 Internal Server Error.

NOTE: If you are adding these defines to a live site, set the third line for WP_DEBUG_DISPLAY to false. A value of true will allow the errors to display live on the website, as a banner across the top of the page.

To save and exit the file:

esc button then :wq

Now anytime you trigger a PHP error, notice, or warning, it will be logged to the file debug.log within the wp-content directory.

To view the entire wp debug log file:cat wp-content/debug.log

If the file is too large, view the last 10 lines only by running:tail wp-content/debug.log

NOTE: Be sure to disable debug logging by delete the lines from your wp-config.php file when you are finished! Debug logs can become very large over time if forgotten and impair performance.

Admin AJAX Logging

Raw access logs won’t show what action the Admin AJAX function triggered. Enable logging of admin ajax actions easily by adding a define to your wp-config.php file. For more information on Admin AJAX, check out this guide.

Use the arrow keys to navigate to the “WP Engine Settings” section. Tap the letter i and then paste the following:

define( 'WPE_MONITOR_ADMIN_AJAX', true );

To save and exit the file, tap the ESC key then enter the following:

:wq

Now any time an Admin AJAX call happens on your website, it will be logged to the __wpe_admin_ajax.log file in your wp-content directory. To more easily notice trends, we recommend using the following command to sort (from the root directory of your website).

Navigate to the root directory of your environment:

cd sites/environment

Actively prints any new Admin AJAX “action”, as they occur on your site:
(At this time you may want to trigger the specified action on the front of your website.)

NOTE: GET requests to admin-ajax.php with arguments on the end, likeadmin-ajax.php?action=do_something&that_something=should_be_cool are not logged. Admin AJAX logs only show POST requests.

If you see an action you’d like to know more about, but aren’t sure which plugin or theme it’s coming from, search for it through plugin and theme files:
(Be sure to replace action_name with the Admin AJAX action.)

ack-grep "action_name" wp-content/plugins/ wp-content/themes/

The above command can take a long time to complete, depending on the number of plugins and themes on your website. Once it does show what plugin or theme is triggering the action, this can give you insight into which setting to adjust or filter, or whether the plugin should be disabled/replaced altogether.

The ack-grep command can be used with some very helpful flags as well, like -i (ignore case distinctions), -o (show only the part that matches the search), and -l (search only file names which match, not file content).

NOTE: Be sure to disable AJAX logging by removing the line from your wp-config.php file when you are finished! AJAX logs can become very large over time if forgotten which will impact performance.

Test PHP Compatibility

Have you ever wondered whether your site is compatible with a new PHP version? Our PHP Compatibility Checker plugin can help with this. While the plugin works great through the Wordcodess Admin Dashboard, you can also trigger the plugin with WP-CLI over the SSH Gateway.

Trigger the PHP compatibility checker to review the active plugins for PHP 7.4:

wp phpcompat 7.4 --scan=active

Check PHP 7.4 compatibility for all plugins and print results to a file:

wp phpcompat 7.4 --scan=all >> _wpeprivate/scan.txt

Remember, the compatibility checker plugin can take a while to run! We recommend only scanning active plugins (using --scan=active instead of --scan=all, and letting it run for a while to complete before reading the output.

Troubleshoot 502 Errors from Autoloaded Data

Are you getting an instant 502 on your website? Often 502 errors mean a process has timed out on the server. But in the case of an instant one, this could mean your site is struggling from too much autoloaded data. You can diagnose autoloaded data issues using SSH Gateway.

Log into your site with SSH Gateway and navigate to the root directory of your website:

cd sites/environment

Run a query to check the total size of autoloaded data. You can do this with the wp db query command from WP-CLI:

wp db query "SELECT SUM(LENGTH(option_value)) FROM wp_options WHERE autoload = 'yes';"
This will output the total amount of autoloaded data in bytes. If the number is over 1 million bytes, you have too much autoloaded data!

Use the following command to print out which autoloaded rows are the largest:

wp db query "SELECT LENGTH(option_value),option_name FROM wp_options WHERE autoload='yes' ORDER BY length(option_value) DESC;"

You will see a list of the largest autoloaded rows in your database (the rows in wp_options that contain the most data). Ask yourself: Does this row need to load on every single page? If the answer is no, you can change that option to say “no” for “autoload” instead.

Update the largest row to “no” autoload:
(Be sure to change myoption to the action option name.)

You can repeat these steps until you have successfully lowered your autoload total to under 1 million bytes. This should resolve your instant 502 error.

Search and Replace with WP-CLI

If you have ever needed to change your website’s domain, you know how much of a pain it can be to change all the references to your old domain over to your new one. With search and replace via WP-CLI, there’s no need to download a plugin. You can simply trigger the search and replace via command line.

Troubleshooting

Share

Share:

Contact the WP Engine Support Team

In order to get expert one-on-one help, please log into your account so we can identify your account and get you exactly the help you need. We offer support 24 hours a day, 7 days a week, 365 days a year.