Troubleshooting a WordPress Website

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
  • Try a different browser
  • Try a different computer
  • Try a different internet network
    • For example, test on a mobile device with the WiFi disabled
  • How does the site load in various locations when testing with a proxy?
    • GeoPeeker
    • kProxy
• 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
  • Update plugins
  • Update your theme
  • Update WordPress core version
  • If you recently updated an item prior to errors, try downgrading it.

---

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.

Learn how to restore your site automatically.
Learn how to perform a manual partial restore.

---

Troubleshooting Safely

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

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.

Server Caching

Learn how to purge the different WP Engine server caches.

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.

Browser Cache

Learn how to purge your browser cache.

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

---

Use a Default .htaccess File

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

• Connect to your site using SFTP
• (Optional) Download the existing .htaccess file
  • 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 .htaccess file 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.

Learn more about which content can be relocated outside of the .htaccess.

---

PHP Version

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.

Learn how to change your PHP version.

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

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.

1. Login to the WordPress admin dashboard of your site
2. Select Settings
3. Click Permalinks
4. 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.

---

Additional Troubleshooting

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.

• Learn about how to diagnose error codes
• Reset File Permissions
• Troubleshoot Using SSH Gateway
• Troubleshooting High TTFB
• Troubleshooting a 502 error
• Troubleshooting a 504 error
• Troubleshooting Missed Crons
• Troubleshooting Global Edge Security (GES) Errors
• Troubleshooting SSH Connection Issues

---

NEXT STEP: Learn how to fix the “white screen of death”