SugarCRM Troubleshooting Simplified - Part I

One of the challenges about working with an open source system such as SugarCRM is the sometimes difficult process of ascertaining the exact source of a technical issue.

Some of the complexity can be attribute to the fact the application is open source, but it is not an issue of open source code being of lesser quality or more complex than code in closed source solutions.  It is rooted in the the fact that because it is open, a user/admin can modify any piece of the code they have access to, potentially impacting the system in unexpected ways.  

Troubleshooting a technical issue within SugarCRM can be a bit difficult at times, however, below are some guidelines that should help you more quickly identify the source of a problem you are facing:

Determine if the problem is system wide or module specific.

If the problem is system wide, your troubleshooting efforts should focus on PHP, Web and Database server configuration, as well as the data itself.  Take note of any modules you may have recently installed.  

Try disabling those additional modules, or uninstalling them if possible, then check if the problem persists.  Language packs have a tendency to cause system wide problems when something goes wrong with them and should be at the top of the list.

The source of module specific problems can usually be rooted out fairly quickly, but finding a solution may not be as easy.  

For module specific scenarios, try the following:

• Rename the [sugar root]/cache/modules/[your problem module] directory and try duplicating the problem
• If the problem persists, rename [sugar root]/custom/modules/[your problem module] directory and try duplicating the problem

In most cases, the problem goes away after renaming the /custom directory.  That would indicate that a customization that has been applied to the system is the source of the problem.  

Examining said folder will reveal a number of different files, depending on the type of customizations that have been applied to the system.  Using the renaming technique on those files should help you pinpoint the exact file that is causing the problem and in turn, provide some clues as to where to make the necessary adjustments to correct it. 

To elaborate, rename the [sugar]/custom/modules/[your problem module] directory to its original name and verify the problem has returned.  Now, rename the files contained in the [sugar]/custom/modules/[your problem module] directory in pairs, checking if the problem persists after each rename.  Repeat the process until the problem goes away and that should tell you which file is causing the problem, e.g. vardefs.php, layoutdefs.php, etc.