Using SSH Gateway to Troubleshoot a Website

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.

---

Diagnosing Issues

Before diving into troubleshooting steps for your website, we always recommend the following steps:

1. Make a backup checkpoint or copy to a staging/development environment
2. Make sure you know how to reliably replicate the issue for testing
3. Note of when the issue 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 prepared, 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)

wp plugin list

List your installed themes:
(Also shows active/inactive states and versions)

wp theme list

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 preventing WP CLI from running, it’s very possible that same error is preventing 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.

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.

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 WordPress core updates come out.

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

If you’re using the Genesis framework, WP CLI resources are available that can help.

WooCommerce has extensive documentation on using their WP CLI commands as well.

---

WordPress Debug Logging

Beyond your WP Engine error logs, you can also enable debug logging for WordPress. Debug mode is enabled by adding a define to your wp-config.php file.

Navigate to the root directory for your website:
(Replace environmentname with your unique WP Engine environment name.

cd sites/yourenvironment

Open the wp-config.php file for editing:

vi wp-config.php

Use the arrow keys to locate the “WP Engine Settings” section and tap i to allow editing of the document, then paste the following:

define( 'WP_DEBUG', true ); #enable debugging
define('WP_DEBUG_LOG', true); #enable debug error log in wp-content
define('WP_DEBUG_DISPLAY', true); #errors display publicly--only do this in stage or dev!

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

---

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.

Navigate to the root directory of your website:
(Be sure to replace environment with your unique WP Engine environment name.)

cd sites/environment

Open the wp-config.php file for editing:

vi wp-config.php

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.)

tail -f wp-content/__wpe_admin_ajax.log | grep "action"

That’ll give you something like this:
10 [action] => ga_stats_widget
2 [action] => heartbeat
1 [action] => do-plugin-upgrade

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).

---

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 WordPress Admin Dashboard, you can also trigger the plugin with WP-CLI over the SSH Gateway.

Install and activate the PHP Compatibility checker plugin on your website:

cd sites/environment

Then run

wp plugin install php-compatibility-checker --activate

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.)

wp db query "UPDATE `wp_options` SET `autoload` = 'no' WHERE `wp_options`.`option_name` = myoption;"

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.

Navigate to the root directory for your website:

cd sites/environment

Trigger a dry run of a search and replace with WP-CLI – does not change any values yet:

(Be sure to update olddomain.com and newdomain.com with their respective values)

wp search-replace 'olddomain.com' 'newdomain.com' --precise --all-tables --dry-run

Trigger a a search and replace with WP-CLI:

(Be sure to update olddomain.com and newdomain.com with their respective values)

wp search-replace 'olddomain.com' 'newdomain.com' --precise --all-tables

There are a lot of really cool variations on this command, like removing specific columns, or only running it on a specific table. Check out the WP-CLI documentation for wp search-replace for more options.

---

NEXT STEP: Check our our full guide on how to troubleshoot a WordPress website