Magento Troubleshooting Fundamentals
When starting out as a developer working on the Magento eCommerce system, it can be confusing and frustrating to find the source of an issue. Here are some basic techniques for finding and resolving problems within Magento:
Magento is built with a sophisticated caching system to speed up the delivery of content to the browser. Even if you turn off all caching, Magento seems to be hesitant to loosen her grip on content without truly clearing the cache folder.
From the filesystem, remove all contents of /var/cache/ If anything has been cached, you will see some folders here titled mage—0 through mage—f. You can safely delete these folders and all contents within them at any time. Magento will rebuild the cache for a page the next time it is loaded.
Magento keeps a steady stream of data flowing by building strong indexes of products, categories, and other entities in the system. Magento will do it’s best to keep these indexes up to date, but if you manually insert data in a database table or have migrated information from another source it may be necessary to reindex your data. The Magento team has quite a bit of useful documentation on how indexes are managed.
To manage your indexes, visit the Magento Admin Control Panel In the navigation, select “System” → “Index Management” From here, you can initiate a manual re-indexing of your data or you can change the mode in which your data is indexed.
When a Magento Blue Screen of death occurs, it tells you a report has been made. You can find the report in your /var/report/ folder in your system. The name of the file is going to be the same as the report ID given on the error screen. The report is simply a stack dump of what Magento did to get to the point where it failed. Read it from the bottom up, you’ll see that the top one or two lines are usually all you need to deduce what went wrong and where it happened.
With so many files being loaded, functions, pages being redirected, ajax requests and a myriad of other places where things could go wrong - you must take full advantage of the system.log.
In nearly any file within Magento, you can call the following line:
This is sent to the system.log. You can also dump arrays or objects to the Magento system log simply by sending them to the system log.
Many times, I’ll SSH into the server, and use tail (http://modernl.com/article/tracking-live-web-logfiles-with-tail-over-ssh) to watch the end of my system log during a process where many things happen in sequence. Tail your log file, then reload your web page and watch the log entries flow in your SSH client.
$ tail -f var/log/system.log
Pro Tip: Add in some PHP Magic Constants (http://php.net/manual/en/language.constants.predefined.php) to your log to get the most out of finding the source of the problem:
Mage::log(__LINE__.': the customer requested a download'); // the line number is added to your log entry
If you have received a white screen, and nothing shows up in your system log - perhaps you have a PHP syntax error which made the page unable to execute. Check your server PHP error log to find a syntax error.
Browser Cookies / Cache
If you are troubleshooting different member types using multiple customer accounts, you can quickly get your browser into a place where session IDs conflict and Magento’s security system keeps you from logging in. Clear your cache and cookies, then restart your browser to bring it back to a clean slate. Many times, we use Chrome’s Incognito mode or Firefox’s Private window modes to make this process easier. When you want to create a new session, simply closing the browser and opening it will start with cookie-free cache-less session.
When troubleshooting Magento, patience is the most important tool in your toolbelt. Use logs and some specific tools to get your environment into a clean condition. Magento can be very sensitive to cookies, caches, indexes and will not give you enough information on the surface. Using these tools, you can squeeze the information you need to find the problem.