Troubleshooting is the technique of ruling out factors until the cause of the issue can be determined. Learning how to troubleshoot a WordPress as an essential process for successful website management.
Start with the Basics
While these first steps may seem too basic or unrelated, it’s best to rule out as many items as you can so you can have confidence when correcting the problem. Something that appears small and basic may end up being crucial to solving a web issue.
- Check the URL
- Does it show the correct domain?
- Is your Domain added in the User Portal?
- Does it show the correct page within your site?
- Should the URL be secure (https) or insecure (http)? Try both!
- Check your user
- Should you be logged in or logged out of your site to see the intended functionality?
- Does the current user have the necessary access to see the intended functionality?
- Change the testing environment
- Use the error logs
- Often the error logs will tell you the malfunctioning file making it easy to disable the offending plugin or theme.
- For a full list of error codes, see our guide.
- Check for updates
Revert to a Backup
If you know the last time the site worked, your best bet may be to simply restore to an earlier checkpoint. WP Engine keeps checkpoints available for automated restore in the User Portal for 30 days. However, WP Engine Support can access backups up to 60 days old, if needed.
Further steps require changes to your site so we suggest a few different options before proceeding.
- Create a Checkpoint
- Create a Staging or Development Environment
- Or, Create a Legacy 1-Click Staging Site
Caching makes your site fast. It’s a necessity and largely unavoidable. Cache exists in several places: the server, your browser, plugins, CDN, even DNS can be cached.
It’s important to purge cache often when testing to ensure you’re seeing updated and consistent content.
Another option is to setup a Legacy 1-Click Staging site. These sites are uncached on WP Engine servers. Bear in mind that they are still impacted by browser and plugin caching, however.
You can also open a new incognito or private window to test with a fresh browser cache. Keep in mind that these sessions carry cache as well, so be sure to close and open a fresh session between tests.
To open a new incognito or private window:Windows, Linux, and Chrome — Press Ctrl + Shift + N
Mac — Press ⌘ + Shift + N
Additional caching layers
- Caching plugins
- Autoptimize, WP Rocket, etc. You may need to check the plugin documentation for steps to purge cache.
- Minification plugins
- While this isn’t technically cache, code is minified into files that may need to be recompiled to show updates.
- Purge Cloudflare cache
- Purge Sucuri firewall cache
Themes and Plugins
Disable all plugins not completely necessary to the function or page you’re testing. Starting with the plugins least necessary or most-recently added may be beneficial if the list of plugins is long.If things work as intended, turn the plugins back on one at a time until the culprit is located, then reach out to the plugin author or find a replacement plugin. Be sure to purge caches between changes.
Change to a Default Theme
We typically suggest using Twenty Nineteen, Twenty Eighteen or one of the other annual themes put out by WordPress, as these are highly tested and considered stable.
Another good idea may be to use a non-customized version of your premium theme, removing any added customizations.If changing to a default theme corrects the issue, then you will need to reach out to the theme support or a developer for additional support.
NOTE: Is an error preventing access to you wp-admin dashboard? Disable Plugins and Change The Theme Using phpMyAdmin
Use a Default .htaccess File
.htaccess file is located in the root of your site’s files that traditionally controlled how Apache reads and interacted with your website. A good step when testing issues on your site is to backup the current
.htaccess file and upload new, default file contents.While you can simply view the
.htaccess and compare it to a default file, we suggest replacing the file completely because there may be minor syntax issues that are easily overlooked.
.htaccess file is located in the site’s root, this is the first directory you will load into if you leave your SFTP user set at the default (blank) file path.
- Connect to your site using SFTP
- (Optional) Download the existing
- This step may save you some time and stress reverting the change later, but isn’t required. If you’re working on a staging/development environment, the file can also be retrieved from a backup or from your production environment.
- Upload a newly created
.htaccessfile using one of the defaults listed here
- Be sure the new file name has a period at the beginning and is spelled correctly, or it will not be read and cause additional issues.
- Ensure the new file replaces the original file on the server. Most SFTP clients will prompt for confirmation if you are overwriting an existing file.
- Purge caches
If this resolves your issue, compare the two files and assess if you need the content from the original
.htaccess file or not. Due to WP Engine’s platform structure, this file should rarely be modified.
PHP is the codebase WordPress, all your plugins and your theme operate on. Version changes can PHP compatibility can cause issues that you may not see immediately especially when the version gap is large (EX: PHP 5.6 to PHP 7.2). It may be a good idea to test changing PHP versions on your site to see if the PHP version is causing problems with your code.
If this resolves your issue, be aware that changing to an older PHP version should only be seen as a temporary fix while you work with a developer to update your code. For security purposes, old versions of PHP are eventually removed from our servers.
Permalinks can be beneficial if your pages are not loading at the URL they should be. They can be accessed at the following location. Be cautious of changing the permalinks on an established site as this can cause widespread 404s and impact SEO.
- Login to the WordPress admin dashboard of your site
- Select Settings
- Click Permalinks
- Ensure the correct Structure is selected
To “reset permalinks”, no changes are needed. Simply Save these settings again. This forces WordPress to regenerate any dynamic URLs.
If you’re still unable to determine what is causing the error on your site, there are some additional options and guide for assessing your issue.
NEXT STEP: Learn how to fix the “white screen of death”