Troubleshooting Guide

WPSSO Core and its add-ons follow all recommended WordPress coding practices, but on occasion, it may break other themes and/or plugins that do not.

If you haven't used the Query Monitor plugin yet, I would strongly recommend you install and activate this very useful plugin. The Query Monitor plugin will highlight any PHP or database query issues, both on the front and back-end. It may not catch all errors (like Ajax queries, for example), so you should also define the WordPress WP_DEBUG constant as suggested below.

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 (see below) 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 we cannot work with text in an image). ;-)

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 must get the error details from the web server's error log to know what the issue really is.

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 Core may be triggering a bug in your theme or another plugin (try disabling WPSSO Core's use of the WordPress content filter as suggested below).

Timeout or Layout Issues

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

WordPress allows plugins and themes to hook hundreds of different filters to manage Post / Page content (some of which are used 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 Core 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" to see if your problem is related to a WordPress filter hook. If unchecking these options fixes your problem, you should determine which plugin or theme is at fault and report the issue with the plugin or theme author. Using the WordPress apply_filters() function should not create timeout or HTML page layout issues.

If you disable the content filter, and your Post / Page content relies upon shortcodes for its text, then you may find that WPSSO Core cannot create accurate description meta tags. WPSSO Core looks for a custom description and excerpt before falling back to using the content text. In the case where content filters are disabled, and the content uses shortcodes for its text, then you may have to enter an excerpt and/or custom description for those Posts / Pages.

Since WPSSO Core uses the custom description and/or post excerpt before falling back the content, using a custom description and/or excerpt for a few Posts / Pages could be another alternative to disabling the content filter for the whole website.

WordPress and PHP Error Messages

Enabling the WordPress debug log (aka WP_DEBUG) is common and very useful. Your theme and/or some badly coded plugins may be generating hundreds of PHP errors and you would never know unless you enabled the WordPress debug log.

To enable the WordPress debug log, without displaying the 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 in your wp-config.php file (as constants can only be defined once). If you do, you can safely remove it and replace it with the following lines.

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.

WordPress or PHP error messages (if any) will be saved in the wordpress/wp-content/debug.log file by default. If you have several badly coded and/or old plugins and themes that generate a lot of errors, then also 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.

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' );