A Rookie Sysadmin’s Guide to Troubleshooting Wordpress
Wordpress is the most popular content management system with more than 60 million websites using it around the globe. It has many themes and plugins that allow a wide range of customization options, so it can support various types of web content: from simple blogs to e-commerce stores or media galleries.
Since it can be configured in so many ways, problems with Wordpress installations are common and system administrators are often required to fix them. In this blog article, we will go through a number of basic troubleshooting steps that address the most frequent issues.
Website Not Loading
If a Wordpress website is down, always check Apache, Nginx, php and MySQL logs for clues. For example, a database table might be corrupt, and you’ll have to repair it.
When a site displays a white page instead of the content, the cause is usually related to a php error. The most common issue is incorrect php extensions, in particular the database one (resulting in the dreaded message: Error establishing a database connection). Older Wordpress versions used the mysql extension, while new ones use mysqli. The database error can also be caused by wrong database connection credentials, which are set in the wp-config.php file.
Here is the list of other php extensions that are required by Wordpress:
curl dom exif fileinfo hash json mbstring mysqli libsodium openssl pcre imagick xml zip
Make sure that all of them are installed and keep in mind that additional extensions are needed by some themes and plugins. A particular situation you might encounter is that php extensions sometimes fail to load properly on shared hosting servers that use Cloud Linux and CageFS. In this case, execute the following command, then try again:
cagefsctl --remount <cpanel_username>
Another common cause of errors is ModSecurity, a security module for the Apache webserver. ModSec rules can block legitimate traffic to a Wordpress site, if it is mistakenly interpreted as an attack. Look for blocked requests in the Apache error logs and deactivate the triggered rules.
A typical request denied by ModSec will look like this in the Apache logs, you will have to inspect such errors one by one in order to eliminate false positives:
[Mon Jun 15 13:47:40.712015 2020] [:error] [pid 32126:tid 47796075890432] [client x.x.x.x] [client x.x.x.x] ModSecurity: Access denied with code 401 (phase 2). Operator EQ matched 0 at REQUEST_HEADERS. [file "/usr/local/apache/conf/modsec/rule_wp_login.conf"] [line "3"] [id "500130"] [msg "wp-login request blocked, no referer"] [hostname "xxx.xx"] [uri "/wp-login.php"] [unique_id "XudRzOoeSi@Ef2Fcai1xGAAAAJU"]
Sometimes, there can be a problem with the Wordpress installation itself, such as empty core files. Restore the files from the latest backup or reinstall the package completely.
If only the homepage is working, while other pages throw 404 errors, the issue is often related to the hidden .htaccess file found in the root of the domain. Rewrite rules might not be configured properly, make a backup of the file and then replace it with a default one.
Last but not least, the website might be hacked. Inspect the files and look for any recent modifications, then check the files themselves. Cleaning the infected files is not enough in this case, you should also fix the root cause by solving any security issues, such as vulnerable plugins.
Infected files will typically include crypted or seemingly random lines, like in the screenshot below:
If a site is unusually slow to load, check the php version. Updated Wordpress always supports the latest php and the difference between php 7.0 and, for example, 7.4 can be significant. Switch to the newest version available and use an info.php file to check if the site actually uses the correct version.
Check the memory allocated to php as well, if the configured value is too low, the site will load very slowly. A modern Wordpress website needs at least 256MB for php processes, so there might be a visible speed improvement if you increase this setting.
General Performance Issues
Sometimes, Wordpress installations use outdated or slow themes, as well as a large number of plugins. Try to switch to a default theme, disable all plugins and then test the speed again. If it works properly, you can enable plugins one by one in order to identify the one that causes performance problems.
Woocommerce or other e-commerce plugins for Wordpress are a special case. Generally speaking, busy e-commerce sites will not work well on shared servers, not even on the largest packages available from hosting providers. Unless a Woocommerce site has really low traffic, there is little to do in such a situation, except migrating to a dedicated machine with more resources.
Troubleshooting Wordpress is a complex topic and this article only scratches the surface. However, we hope the steps detailed here will be helpful in fixing some of the most common errors.
About the Author
Dragos Baldescu is a Level 2 Technical Support Engineer at Bigstep, passionate about Linux and testing out new technologies and solutions.