Knowledge Base

Ultimate debug guide for WordPress

Issues with new themes and plugins can be one of the most frustrating things for website admins working with WordPress. This handy guide has been designed to help you get to the bottom of issues with themes and plugins.

This guide has been distilled from thousands of customer interactions with the HeroThemes support team. It is the same one we use internally, rewritten to help you get to the bottom of the most troublesome WordPress SNAFUs.

Conflicts with third party plugins

Issue:

With over 56,000 plugins on the public directory at the time of writing and thousands more premium plugins, conflicts are are a common issue for WordPress sites. While some conflicts result in obvious issues on a site, others can be more subtle and difficult to detect and isolate.

Fix:

Identify the conflicting plugin and report to the plugin developer or find an alternative plugin for the

Disable all the 3rd party plugins temporarily, except the one you are testing against (eg. all non-HeroThemes plugins). If the issue disappears when you do this, there is a plugin conflict. Re-activate and test each plugin in turn to identify problematic plugins.

Tips:

Some themes such as KnowAll include packaged plugins, that can not be disabled while the theme is active. To disable such plugins, switch to a default theme, such as Twenty Nineteen or Twenty Seventeen, which should be available as a pre-installed WordPress theme.

If you have a large number of plugins that you are testing, tools such as Plugin Detective can automate the process of isolating troublesome plugins

Custom code

Issue:

Customizations and code snippets are typically used in child themes to change the behaviour or appearance of a site. More advanced customizations should be implemented a custom plugins, which can be enabled and disabled in isolation of the original functionality.

Fix:

If the customization has been implemented in a child theme, as is best practice, switch to the parent theme to verify the customization

Tips:

Never implement a customization by changing core WordPress files, plugin or theme files directly. This ensures that issues can be isolated more easily and the core files can be updated without affecting any modifications, as updates often overwrite any changes.

Where possible use hooks and filters, in addition to the WordPress standard filters, many developers have their own which often offer a better way to ‘hook’ into functionality.

Most developers do not support customizations, this is because the amount of work to review, support and debug custom functionality is too great. Convention dictates that custom functionality is typically supported by the development team that implemented the code, or by a dedicated freelance specialist such as WPMatic.

Out of date WordPress installation

Issue:

WordPress is constantly evolving, adding new features and fixing security issues. Because WordPress is a self-hosted platform, website owners often need to manually process updates from the WordPress dashboard.

Running old versions of WordPress can lead to compatibility issues with themes and plugins. Some functionality may rely on features only available in newer versions of WordPress.

Fix:

Update to the latest version of WordPress. Provided your site can communicate with the WordPress update system, you’ll receive a notification on the administration dashboard when an update is available.

As with any modification to your site, it’s always advisable to make appropriate backups prior to applying updates.

Tips:

You can check the current releases from the WordPress Versions page here. The latest version is available for download from the WordPress download page here.

Out of date plugins or themes

Issue:

As WordPress can become outdated, so too can plugins and themes.

Theme and plugin updates often include bug fixes and improvements that can enhance the user experience and security of your site. They may also fix compatibility issues and improve performance.

Fix:

Update out-of-date themes and plugins to the latest version. As with any update, make appropriate backups, so any changes can be rolled back if an updates breaks more than it fixes.

All available updates can be viewed by clicking the update icon in the top left of the admin toolbar in the dashboard, the number of available updates will be displayed.

Premium plugins and themes, such as HeroThemes KnowAll package, require you activate your license to receive automatic updates. Themes and plugins from WordPress.org will notify and update on demand from the repository.

Tips:

Many themes and plugins include an update log of the changes in each release, to indicate the enhancements and fixes made. You can find the change log for HeroThemes products here.

Issue:

The permalink structure allows you to use meaningful names to reference your content, by default and compatibility with the most web hosts, WordPress will use the post ID as the post permalink eg ?p=123, this is called an ugly permalink.

WordPress also allows for pretty permalinks, where the link is structured to reflect the site content and the URL reflects the content being displayed. This provides for improved contextual URL structures, such as content publication date or post titles.

Fix:

Change the permalink to something other than default.

From the WordPress admin dashboard, find the permalink settings in Settings > Permalinks. The Post name setting is recommended for most sites, if your host supports.

Tips:

You can set the last part of the permalink for individual articles, known as the slug, from the article edit screen. Simply click the edit button, next to the permalink.

Browser and Server Caches

Issue:

Caching is a great tool for increasing the speed of your site, it can reduce load on your server and provide a better experience for visitors.

Caching may be done at the browser or server level, depending on the content.

The issues arise when caches do not clear when they are supposed to, leading to outdated/expired content being served to visitors.

This can result in visitors seeing out of date pages, with old content or experience issues with website features that rely on security tokens.

Caching issues can lead to odd issues that can be tricky to diagnose, so it’s always recommended to clear caches first if experiencing issues.

Fix:

Clear browser and server caches. Depending on your browser and server caching mechanism, this is done in different ways.

For the browser cache there are guides for Firefox here and Chrome here. You can check for browser cache issues by accessing your site from a new incognito/private window.

For server caches, if you’re using a plugin, you’ll need to consult the documentation. If the cache is on a server level – you may have server caching and not even know about it, contact your web host.

Tips:

Caches can be stubborn, make sure you try different browsers, and log out and back into WordPress to help purge outdated cache. Server caching issues can be particularly problematic to diagnose as it’s not easy to test alternative setups. Resolve caching issues methodically.

SSL Backend, non-SSL frontend

Issue:

This is usually the cause of ‘mixed content warnings’ where different parts of a site are loaded over a combination of secure (https) and insecure (regular http) connections.

With the voting functionality enabled in some HeroThemes products you may see a ‘Security check – voting callback’ error if your site has a SSL enforced backend, but loading frontend via regular http.

Note is now recommended that all sites secure content with SSL and Google are now using it as a ranking signal. That is, websites that do not serve content securely may see a detrimental impact on their SEO and rankings.

Fix:

Ensure that both the frontend and backend content is served over SSL.

Providing you already have an SSL certificate – that is, you can prefix your site’s URL with https and it works OK, this can be straightforward. This is typically done by changing your WordPress Address and Site URL from http to https.

More work may be required for sites with existing content, as existing http URLs found in internal links and references to media, such as images, will need to be redirected to https using a .htaccess rule. There are several plugins such as Really Simple SSL that can handle this sort of SSL migration

Tips:

If you can’t address your site with https, you will need to obtain and install a SSL certificate, this is typically handled by your web host, so contact them for further advice and assistance.

You can get a free SSL certificate from Let’s Encrypt, again, some web hosts have an automated SSL feature available, depending on the host and plan.

Installing a plugin or theme incorrectly

Issue:

Unless installing directly from the theme/plugin directory, theme and plugin packages are supplied as .zip files. Premium theme and plugins are always supplied as zip packages.

It important to install a plugin or theme from the correct section of the WordPress admin dashboard, otherwise an error message such as ‘The theme is missing the style.css stylesheet.’ or ‘No valid plugins were found.’ One of these message usually indicates the theme/plugin

Fix:

Ensure you are installing from the correct section, for a plugin, this is from Plugins > Add New. For themes, Appearance > Themes, then the Add New button.

If you’re unable to identify if a zip file is a theme, check the package contains a style.css file. Likewise, plugins will contain a file with a plugin header, that identifies the plugin.

Tips:

For HeroThemes products, the installable file will be the name of the theme or plugin, all in lowercase, possibly followed by the version number and have the .zip extension. Opening the zip file you’ll be able to see style.css in themes straight away, which WordPress uses to identify a theme pack, otherwise it’s a plugin.

Support Checklist

  • Conflict with 3rd party plugin or theme?
  • Customisations? Child themes or custom plugins?
  • Out-of-date WordPress?
  • Out-of-date plugins or themes?
  • Permalink Structure?
  • SSL Issues?
  • Incorrect plugin or theme installation?

Was this article helpful?

Related Articles