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.
Permalink Structure
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.
Common issues noted in the documentation
Issue:
Many themes and plugins are designed to be straightforward to use, often using in product guides and assistants. Where this is not possible, the documentation is written to be a reference guide for installing, configuring and using the product.
The documentation often indicates how the product is meant to be used. If something isn’t working it may be that it’s not designed to be used in such a way, or there’s a specific way of achieving a result, checking the documentation should confirm this.
Fix:
Read the documentation, seriously. Not just to help head off common issues, but in order to make the most of your new theme or plugin. There may be a ton of potential just waiting in the documentation, that is not possible to communicate effectively in-product.
The documentation may hold the answers to frustrating issues and help you discover new features and functionality that were not obvious.
Tips:
Don’t skip the red bits and notes in product documentation, these are points the developer wishes to emphasise. If it’s in red/yellow, it’s probably important and you may want to read it.
Getting Help
When things go wrong, it’s important to know what to do and where to get help.
If you’re getting an unexpected result or error message, you should search the message text in your favourite search engine. This may bring up an obvious solution, but some issues may be unique to a particular configuration. In such cases also be sure to add keywords describing the unique elements to your setup, such as error message X with plugin A with theme B.
For issues with your server, your host is the first point of contact for assistance. This includes configuration issues, working with files and folders and general server management.
For generic issues try searching for the symptoms such as ‘WordPress white screen’ or ‘WordPress login fails’.
For How do I…? Questions, the WordPress support pages or product documentation are good starting points. Finding out how something should work is the best way to identify when something is not right.
If there’s a specific issue in a theme or plugin, the author is the next point of assistance. Be sure to consult their documentation and search their support resources – such as knowledge base or support forum
If you have to reach out directly for assistance, be sure to include as much relevant information about the issue as possible. Describe the symptoms, what you expect should be happening, what is actually happening and the steps to reproduce the issue. Where possible, include screenshots (annotated as appropriate).
WordPress provides limited information to help with debugging issues, some products include a debug log, which should accompany any support requests in order to quickly identify or exclude configuration and conflict issues.
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?
- Common issues noted in the documentation?