Documentation > Plugin Documentation > WPSSO Core Documentation > WPSSO Core Installation and Setup

Troubleshooting Guide

JS Morisset

Table of Contents

The WPSSO Core plugin and its add-ons follow all recommended WordPress coding practices, but on occasion it may break other themes or plugins that do not. This troubleshooting guide will help you identify and mitigate some common issues.

The Query Monitor Plugin

If you are having issues with your WordPress site, related to WPSSO or not, and haven't used the Query Monitor plugin yet, we recommend that you install and activate this very useful plugin. The Query Monitor plugin will report any PHP or database query issues, both on the front and back-end. It may not catch all PHP errors (like ajax queries or scheduled tasks, for example), so you may also want to also define the WordPress WP_DEBUG constant as suggested below to enable the WordPress error log (which is not enabled by default).

JavaScript and jQuery Errors

Since the advent of page builders and the new block editor in WordPress v5, JavaScript and jQuery errors have become more common and are not easily diagnosed using standard WordPress debugging methods (like defining the WordPress WP_DEBUG constant and using the Query Monitor plugin).

To view JavaScript and jQuery related errors, you must enable your web browser's console, and how you do that depends on the web browser you use (see this Google search result for more information on that). It's definitely worth enabling your web browser's console to make sure there are no JavaScript and jQuery errors. If there are, you can select the error and copy-paste the error text into a new support ticket (please do not submit screenshots as text in an image is not text). ;-) JavaScript and jQuery errors are probably not caused by WPSSO Core or its add-ons, but we're happy to help you diagnose the issue and propose a solution.

HTTP Error Code 5xx

A web server may display an HTTP 5xx error page (500, 502, etc.) with a generic error message. This error message is generic on purpose - the actual details of the error can be found in the web server's error log. The most common cause of an HTTP 5xx error are from lack of available memory when PHP is executing - for example, when creating thumbnails from large images, executing a bloated plugin, executing a badly coded recursive filter, etc. If you are seeing an HTTP 5xx error message, you can get the error details from the web server's error log. This will tell you what caused the HTTP 5xx error code.

Some older versions of PHP are known to have bugs in their ImageMagick library, or PHP may have timed-out when trying to create several thumbnail images in a row (see this FAQ for details), or PHP may have run out of memory (see this FAQ for details), or WPSSO may be triggering a bug in your theme or another plugin (try disabling WPSSO's use of the WordPress content filter as suggested below).

Performance or Layout Issues

Related FAQ: Why are some HTML elements missing or misaligned?

WordPress allows themes and plugins to hook hundreds of different filters to manage the Post / Page content (some of these filters are called by WordPress to expand shortcodes, for example). WordPress generally calls a filter (like 'the_content') once to expand text for a given post within the loop or a single webpage. As a consequence, some authors mistakenly assume that a filter they have created will only be executed once for a given post, and only within the webpage body or specific area. WordPress filters are available to any theme or plugin that needs to expand text (title, excerpt, content, etc.), and in any context (header, loop, widget, admin, etc.). WPSSO uses 'the_content' filter to locate media elements within the content and to provide complete and accurate description meta tags.

See the "Is your filter going to break the layout?" post on the Make WordPress Plugins blog for additional information on the use (and common misuse) of 'the_content' filter by developers.

Under the SSO > Advanced Settings > Plugin Settings > Integration tab, you can uncheck the "Use Filtered Content" and "Use Filtered Excerpt" options to see if your problem is related to a WordPress filter hook. If disabling these options fixes the problem, you should determine which theme or plugin is at fault and report the issue with to theme or plugin authors. Using the WordPress apply_filters() function should not create timeout or layout issues.

If you disable the content filter, and your Post / Page content relies on shortcodes for its text, then you may find that WPSSO cannot create accurate descriptions for its meta tags and Schema markup. WPSSO looks for custom descriptions and excerpts before falling back to using the content text. If the the "Use Filtered Content" option is disabled, and the content relies on shortcodes for its text, then you may have to enter custom descriptions and excerpts for those Posts / Pages.

WordPress and PHP Error Messages

Enabling the PHP and WordPress debug log (aka WP_DEBUG) is a common practice and very useful. Your theme and/or badly coded plugins may be generating hundreds of PHP and WordPress errors, and you would never know unless you enabled the WordPress debug log. To enable the WordPress debug log, without displaying those errors to your visitors, add the following to your wp-config.php file. Make sure you do not already have a define() for WP_DEBUG, WP_DEBUG_LOG, or WP_DEBUG_DISPLAY in your wp-config.php file (as PHP constants can only be defined once). If you do, you can safely remove them and replace those lines with the following:

define( 'WP_DEBUG', true );

if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {

    define( 'WP_DEBUG_LOG', true );

    define( 'WP_DEBUG_DISPLAY', false );

    @ini_set( 'display_errors',0 );
}

You can turn on/off the WordPress debug log by changing WP_DEBUG's value from true to false.

The default location of the debug.log file can be changed by specifying a file path for the WP_DEBUG_LOG value.

define( 'WP_DEBUG_LOG', WP_CONTENT_DIR . '/debug.log' );

Any WordPress or PHP error messages will be saved to the wordpress/wp-content/debug.log file by default. If you have several badly coded and/or old themes and plugins that generate a lot of errors, make sure you clear the contents / rotate this file regularly, as it could grow large enough to fill a filesystem. In all cases, you should endeavour to resolve all warnings and errors in the debug.log file.

HTML Debug Messages

In some instances, WPSSO support may request that you enable the "Add HTML Debug Messages" and "Disable Cache for Debugging" options under the SSO > Advanced Settings > Plugin Settings > Plugin Admin tab to investigate an issue specific to your site (ie. that cannot be reproduced on a test site). After enabling the "Add HTML Debug Messages" and "Disable Cache for Debugging" options, the WPSSO Core plugin and its add-ons will include debug messages as HTML comments in your webpages. If you use an optimization plugin or service to remove HTML comments from your webpages (a feature that can also be part of a caching plugin or service), you will need to disabled that feature. Once WPSSO support has investigated the issue, you can disable the "Add HTML Debug Messages" and "Disable Cache for Debugging" options and re-enable any HTML optimization features.