Troubleshooting tips

From time to time when building CMSMS websites, writing code, or using a third party module or plugin you may experience strange behavior requiring you to do some troubleshooting. Below are some tips and techniques that you can use to assist you:

   Clear cache

If something about the 'environment' of your CMS Made Simple installation has been changed (e.g. moved to another server, folder or domain, changed settings in config.php, your hosting provider upgraded the version of PHP, etc.) you might need to clear the cache.

Preferably you do so from within the CMSMS admin console: Site Admin » System Maintenance » Cache and content. If the CMSMS admin panel is unavailable and you do have file system access, you can manually clear the cache by removing all files inside the following folders:

tmp/cache
tmp/templates_c

It is possible that a system administrator changed the default location of one or both cache folders by adding entries in the config.php file. For more information check tmp_cache_location and tmp_templates_c_location.

Although clearing the cache is safe to do, it is always a good practice to have a proper backup of both the file system and the database.

   Enable debug mode

When searching for the cause of a problem you can enable debug mode in CMSMS to show error messages that may be hidden.

Add to (or change in) the config.php file:

$config['debug'] = true;

When you are ready simply add a hash (#) before this line or set it to 'false'.

#$config['debug'] = true;
$config['debug'] = false;

Some hosts will disable error reporting in production servers by default, or may not provide access to logs. Unfortunately the steps to ensure that error reporting is enabled differ based on the software that is used on the server, and the configuration of the server. If you are experiencing errors, and are not seeing error messages in your logs, or do not have access to your logs you may have to contact your host for assistance in obtaining the necessary error information.

If a symptom to the problem you are trying to troubleshoot is that you see the headers to the tabs of a CMSMS admin page, but none of the intended content searching for the words "Error", "Notice" or "Warning" in the HTML source of the page may be useful.

   Error Logs

If you are receiving a "error 500" message, a blank white page, or a hanging system (fails to complete downloading), or other problems you may find hints to your issue in the error logs. Error messages typically describe the error (in technical terms) and provide the file name and line number in the program code where this error occurs.

All web servers are capable of producing error messages for a number of problems. You can often diagnose simple problems by finding these message, then looking up what they mean. Often web hosts will make access logs and error logs available to you via ftp or by your webhosts admin panel. If you are having difficulty finding them, please ask your host.

Additionally, CMSMS attempts to trap some errors in its admin log. You may have success looking under "Site Admin » Admin Log" in the CMSMS admin console.

   PHP Information

To display the PHP Information of the server, simply create a new UDT named phpinfo and with the content:

phpinfo();

Put the tag {phpinfo} in a page, and in the frontend it will show your server information.

   System Information

In the CMSMS admin panel you will find a summary of the most critical server settings. You will find it at
Site Admin >> System Information

In the top right corner of the System Information page you will find a link "View Text Report".
Clicking on it will display a page suitable for copying into forum posts.

   Get template variables

If you want to know what smarty variables are available in a template, place the following tag to your template (summary, detail, page or any other template) and you will get variable list on you screen:

{get_template_vars}

   print_r

To get a variable dump of a smarty object or variable, do something like this:

{$var|print_r}
{$item|print_r}
{$entry|print_r}

   Pretty URLS

If diagnosing problems with the submission of forms, or with redirection it may be useful to temporarily disable pretty urls in the config.php

#$config['url_rewriting'] = 'mod_rewrite';

and/or temporarily remove any .htaccess file.

mv .htaccess htaccess.notused

   Validate

If experiencing problems with layout, particularly cross browser issues, or form submission problems before reporting an issue in the CMSMS forum ensure that your HTML code validates (or that all reported validation errors are expected and understood. For example, the facebook fb:like plugin may not validate.). See The W3C Markup Validation Service

   Javascript

If experiencing problems with layout, form submission, slideshows, or other custom behavior it is important to understand any and all javascript errors. All browsers have the ability to display an error console of some sort. In Chrome the javascript console can be accessed by pressing Ctrl+Shift+J

   Browser Add-ons

There are a number of useful tools and plugins for all major browsers that will assist in web development and troubleshooting. If you want to see what the Dev Team are currently using, why not drop into Slack and ask us?