How to Troubleshoot Like a WP Engine Tech with SSH Gateway

With the release of SSH Gateway on WP Engine, customers on dedicated servers have the ability to manage, maintain, and troubleshoot their sites in a brand new way. 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:

• Take a backup of your website in the User Portal
• Make a note of replication steps – before troubleshooting, make sure you know how to reliably replicate the issue for testing purposes
• Make a 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 see any User Portal changes.

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

Disabling Plugins and Themes

Have you ever run into an error on your website, and weren’t sure why? 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. Here’s how:

# list your installed plugins
wp plugin list

# list your installed themes
wp theme list

If this command spits out an error, look and see which plugin or theme it’s referencing and see the section on disabling to turn it off. To get the command to run in spite of a plugin or theme error, add --skip-plugins and --skip-themes to the end like this:

# list your installed plugins, skipping any fatal errors
wp plugin list --skip-plugins --skip-themes

# list your installed themes, skipping any fatal errors
wp theme list --skip-plugins --skip-themes

To disable a plugin or theme you suspect to be the culprit, use the following commands. Be sure to enter the plugin or theme name as it appears in the “list” command used earlier! Remember: your site always has to have a theme enabled, so to disable a theme, you have to enable a different one.

# disable the co-authors-plus plugin
wp plugin deactivate co-authors-plus

# activate the default twentyseventeen theme
wp theme activate twentyseventeen

You can also choose to disable all plugins at once using the --all flag, or disable only active plugins using the --active flag.

# disable all plugins
wp plugin deactivate --all

# disable only active plugins
wp plugin deactivate --active

Remember, if you see a fatal error instead of output, use the --skip-plugins and --skip-themes flags! There are a lot of other useful WP-CLI commands you can use to help manage your website via command line. Be sure to check out the WP-CLI documentation for more useful examples.

Inspect and Edit the .htaccess File

The .htaccess file is a configuration file which must be loaded on every single uncached page in WordPress. Because of this, a misconfiguration in this file could cause your entire site to show a blank white screen (known as the White Screen of Death) or a 500 Internal Server Error! If you can’t access your site, how can you troubleshoot it? Using SSH Gateway, of course.

First, login to your site using SSH Gateway and navigate to your site’s root directory.

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

Now show what’s in your .htaccess file using the cat command.

# print out the contents of .htaccess
cat .htaccess

Does anything look off? Is there a weird apostrophe, semicolon, or curly brace in there? You can fix it by entering your favorite command-line text editor.

# edit .htaccess file
vi .htaccess

If you’re not sure what is wrong, you can copy over everything in your .htaccess file with the default for WordPress, found in their documentation. Once you have made your changes, refresh your site and make sure this has resolved your issue.

Debug Logging

If you’ve ever written some PHP code and were mystified as to why it silently failed, debugging in WordPress is about to get a lot easier! Beyond your WP Engine error logs, you can also enable debug logging for WordPress. Debug mode is enabled in your wp-config.php file, so you will need to use your favorite command-line text editor.

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

# use your favorite command-line text editor to open the file
vi wp-config.php

# paste the following lines into the “WP Engine Settings” section
define( 'WP_DEBUG', true ); #enable debugging
define('WP_DEBUG_LOG', true); #enable the logging of errors  in the wp-content folder
define('WP_DEBUG_DISPLAY', true); #make errors display publicly--only do this in staging!

Now anytime you trigger a PHP error, notice, or warning, it will be logged to a debug.log file in your wp-content folder.

# view the last 10 lines of the debug log (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment/wp-content && tail debug.log

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

AJAX Logging

If you’ve ever discovered a plugin running amok with a crazy number of admin-ajax requests, it may be super frustrating to try to find the source of the issue. Raw logs won’t show what action the admin-ajax function triggered. With SSH Gateway, you can enable logging of these actions to more easily find the source of the issue.

First, we need to add a line to the wp-config.php file, which requires using your favorite command-line text editor. This will enable the logging.

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

# use your favorite command-line text editor to open the file
vi wp-config.php

# paste the following lines into the “WP Engine Settings” section
define( 'WPE_MONITOR_ADMIN_AJAX', true );

Now anytime an admin-ajax call happens on your website, it will be logged to the __wpe_admin_ajax.log file in your wp-content folder. 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 (replace yourenvironment with your WP Engine environment name) and sort for AJAX actions
cd sites/yourenvironment
tail -f wp-content/__wpe_admin_ajax.log | grep "\[action\]"

This will present you with a list of actions, most commonly triggered by a plugin or theme on your website. You can search for the action throughout your plugins and themes with the following command.

# search for the "ga_stats_widget" action in your plugins and themes (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment/wp-content/
ack-grep "ga_stats_widget" plugins/ themes/

The above command can sometimes 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). 

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.

Test PHP Compatibility

Have you ever wondered whether your site is compatible with a specific PHP version? This is possible with our PHP Compatibility Checker plugin! While the plugin works great through the WordPress Admin Dashboard, you can also trigger the plugin with WP-CLI via SSH Gateway.

First, install the plugin on your website. You can do this step with command-line too!

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

# install and activate the PHP Compatibility Checker plugin
wp plugin install php-compatibility-checker --activate

Now, trigger the check via command line. You can change the version (5.3, 5.4, 5.5, 5.6, 7.0, 7.2) and choose to scan only active plugins, or all plugins.

# check compatibility for PHP 7.0 on only active plugins
wp phpcompat 7.0 --scan=active

# check compatibility for PHP 5.6 for all plugins, and save the output to a "scan.txt" file in your _wpeprivate folder (run from the root directory for your website environment)
wp phpcompat 5.6 --scan=all >> _wpeprivate/scan.txt

Remember, the compatibility checker plugin can take a while to run! We recommend only scanning active plugins, and letting it run for a while to complete before reading the output.

Troubleshoot 502 Errors from Autoloaded Data

Have you ever received an instant 502 error 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!

First, log into your site with SSH Gateway and navigate to the root directory of your website.

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

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

# use wp db query to get the total size of autoloaded data
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! If that’s the case, use the following command to print out which rows are the largest.

# use wp db query to get the total size of autoloaded data
wp db query "SELECT SUM(LENGTH(option_value)) FROM wp_options WHERE autoload = 'yes';"

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.

# use wp db query to alter the largest row to not autoload (be sure to change "myoption" to reflect the actual option_name in the output from above)
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 new plugin. You can simply trigger the search and replace via command line! Please note, it is best to perform a backup before and after this step, using the User Portal.

First, navigate to the root directory for your website

# navigate to the root directory for your website (replace yourenvironment with your WP Engine environment name)
cd sites/yourenvironment

Now, trigger a search and replace with WP-CLI.

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

You can also try a dry-run first, to make sure the replacements look right before running the full search/replace.

# try a search-replace dry-run first
wp search-replace 'olddomain.com' 'newdomain.com' --precise --all-tables --dry-run

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.