SugarCRM Troubleshooting: Formatting Woes

Does the image below look familiar?

It is the default login screen for SugarCRM Community Edition, but as one can see, the formatting is not quite right. This, unfortunately, is a common occurrence and worse yet, it usually occurs immediately following the install process.

Fortunately, the solution is rather simple. But before we get into the solution, let us spend just a couple of minutes reviewing the source of the problem so that we have a better understanding of the SugarCRM internals, which may come in handy at a later time.

Normal operation of SugarCRM requires the use of files stored in a folder named cache and located within the root SugarCRM install folder. If one were to browse said cache folder, one would find a variety of sub-folders such as modules, upload and others. The files contained in these folders are rather important to the look and feel of SugarCRM, as well as other operations.

For example, the modules folder contains templates that SugarCRM uses for the various views within the system, i.e. ListView, DetailView, EditView. In short, they are HTML templates that make the system function faster, as the page does not have to be recreated every time a user accesses one of the views.

Were we to continue examining the additional contents of the cache folder, we would also find the theme files that actually make SugarCRM look pretty. That includes graphics, JavaScript code and a style sheet, better known as CSS. 

This brings us back to the solution. The reason why the behavior portrayed in the image occurs is because the web server is unable to access the files that apply the cosmetic changes. i.e. The web server cannot properly read the cache folder. 

This is not an uncommon occurrence if one is using a Unix like operating system such as Linux, which is a rather popular platform for hosting accounts.

To correct it, we need to adjust the permissions to allow the web server proper access. This is usually accomplished by executing one (or both) of the following commands (Linux):

chmod -R 755 <sugar>/cache

and/or

chown -R <apache>.<apache_group> <sugar>/cache

Note that <apache> represents the user under which the web server is running and <apache_group> represents the user group that said user belongs to. 

Often times, specially those with hosting accounts, one will not have access to the shell to execute these commands. In such cases, one should use an FTP tool such as FileZilla to apply the proper settings, making sure to select the option to apply the changes recursively, including all subfolders and files.

IMPORTANT: Users often report that the problem persists even after applying the changes. This is usually because the changes have not been applied recursively. Attempting to apply these changes via tools such as cPanel will not yield the intended results as cPanel does not apply the changes recursively.

As a final note, it is also worth noting that the cache folder grows over time. For example, if one examines it immediately after installing SugarCRM and then again after using Dashboards or features which are heavily reliant on JavaScript (such as Studio), one would will note that there are more files within the folder. This sometimes causes similar permissions problems that cause the display issue discussed herein and require that you re-apply the settings.

So, if you notice odd visual problems, your Dashboards do not work or Studio, Email or other JavaScript rich features are malfunctioning, check out your permissions. And for those on Windows, the problem is less likely, but if you do encounter it, right click the cache folder and verify that IUSR has access to the folder and its contents (recursively).