Fundamentals for debugging a Magento store

Question

How can I debug my Magento store

This is a question that isn't all too relevant to us now, but had a Magento SE site existed 5 years ago, it probably would have been our first question. For those just getting into Magento, or unfamiliar with it - knowing the fundamentals of debugging can be key to rule out the cause of issues. And despite its irrelevance to us now we're pre-empting this question appearing with a self-answered approach.

Help my site is down!

1. Is my design at fault?
2. Is a 3rd party module at fault?
3. Why can't I see the error?

Each of these questions can readily be answered by following a standardized approach to debugging that even the most basic of users can complete. By means of a process of elimination of the fundamentals of debugging a Magento store.

Answer 1

Debugging is a bit of an art, but something that can easily be mastered by following a simple regimen.

Follow each point until you finally reach a solution.

---

Enable PHP Errors

This is key to most issues. For security or other reasons, PHP error display could likely be disabled by default by your PHP configuration.

You can enable errors with a more permanent solution, or merely something more temporary.

Permanent solution

For Apache/mod_php users

In your document root's .htaccess file - just drop this at the top.

php_flag display_startup_errors on
php_flag display_errors on
php_flag html_errors on
php_flag  log_errors on
php_value error_log  /home/path/public_html/var/log/system.log

For Nginx/FastCGI users

In your Nginx virtualhost configuration, in either the final location .php { directive, or in the fastcgi_params file (if you have one specified)

fastcgi_param PHP_VALUE  display_startup_errors=on;
fastcgi_param PHP_VALUE  display_errors=on;
fastcgi_param PHP_VALUE  html_errors=on;
fastcgi_param PHP_VALUE  log_errors=on;
fastcgi_param PHP_VALUE  error_log=/home/path/public_html/var/log/system.log;

Temporary/Universal solution

For any platform

Edit the Magento bootstrap index.php in your document root and uncomment the following line:

#ini_set('display_errors', 1);

---

Enable Developer Mode

When you've had an error and suddenly hit the "Error Report" page, and been given a seemingly useless error string like 1184257287824 - you've got a few options.

Permanent solution

For Apache/mod_php users

In your document root .htaccess file - just drop this at the top.

SetEnv MAGE_IS_DEVELOPER_MODE true

For Nginx/fastcgi users

In your Nginx virtualhost configuration, in either the final location .php { directive, or in the fastcgi_params file (if you have one specified)

fastcgi_param MAGE_IS_DEVELOPER_MODE true;

Temporary/Universal solution

Edit the Magento bootstrap index.php in your document root and either make the if statement always true, or enabled for your specific IP.

if (isset($_SERVER['MAGE_IS_DEVELOPER_MODE']) || true) {
  Mage::setIsDeveloperMode(true);
}

or

if (isset($_SERVER['MAGE_IS_DEVELOPER_MODE']) || $_SERVER['REMOTE_ADDR'] == 'my.ip.add.ress') {
  Mage::setIsDeveloperMode(true);
}

---

Check your permissions

Incorrect permissions will cause a wealth of problems, a lot of which are not that easy to find at first glance.

For example.
If PHP cannot write to the ./media directory and you have JS combine enabled - Magento is unable to generate the combined file and associated unique URI for the media. So instead, what you'll find in your browser source code is a full server path to the media file /home/path/public_html/media/xxx

Otherwise, the site can appear to be functioning as normal - with no critical errors actually visible.

Please bear in mind, this practice is secure for dedicated hosting but may present security issues with shared hosting if the Apache process isn’t chroot’ed per user.

In our example, the SSH/FTP user is sonassi, the Apache user is apache and the group is apache

Add the FTP/SSH user to the Apache group

Most importantly, we need to make sure that the FTP/SSH user is part of the Apache group, in our example, its apache (but is also commonly www-data)

usermod -a -G apache sonassi

Keep adding as many users to the group as you have for FTP/SSH.

Reset original permissions

So before we start, lets make sure all the permissions are correct.

chown -R sonassi:apache /home/path/public_html/
find /home/path/public_html/ -type d -exec chmod 775 {} \;
find /home/path/public_html/ -type f -exec chmod 664 {} \;

Making the changes permanent

ACLs and Sticky Bits

ACLs in Linux allow us to define specific rules, in our case, what permissions files should inherit upon creation. A sticky bit (mentioned later) takes care of group inheritance, but does not help with the permissions, which is why we use ACLs.

Start by enabling ACL support on the active partition, please ensure your Kernel was compiled with ACL support.

Your partition may be /, /home, /var or something else, replace as appropriate.

mount -o remount,acl /home

Now ACLs are enabled, we can set the ACL rules and group sticky bits:

setfacl -d -m u::rwx,g::rwx,o::rx /home/path/public_html/
chmod g+s /home/path/public_html/

But I don’t have ACL support

If your Kernel doesn’t support ACLs you can also use umask (which is a run time setting for BASH, FTP and PHP) to set the default file permissions. Magento usually sets umask(0) in index.php, however, it would be in your interests to change this.

In your index.php change the umask line to be

umask(022);

And in your BASH environment for SSH, set this in either your .bashrc or .bash_profile

umask 022

For your FTP server, you’ll need to read the documentation for it, but the principle is the same.

---

Revert theme to default

Its possible that either your theme or package is responsible for this issue. Reverting back to a vanilla Magento theme is a quick way to find out.

**This comes with the caveat that some modules may be dependent on certain theme features*

Rather than change anything via the admin panel, it is much simpler to merely rename the offending directories.

Via SSH

mv ./app/design/frontend/myBrokenTheme{,.tmp}
mv ./skin/frontend/myBrokenTheme{,.tmp}

Or via your FTP client, traverse and rename your package to something else. eg. myBrokenTheme.tmp

If this resolves your issue

Then you need to dig a bit deeper as to what part of the template is problematic. So restore your package and attempt the following, testing between each.

Essentially, the process is to gradually enable directories as you traverse down the file tree - until you can find the offending file.

1. Rename the layout directory to .tmp
2. Rename the template directory to .tmp

Then if either yields a fix, rename all files within the layout directory to .tmp - (for the SSH users ls | xargs -I {} mv {} {}.tmp or rename 's/^/.tmp/' *)

Then gradually enable each file 1 by 1 until resolved.

If this doesn't resolve your issue

There is potential that your base/default or enterprise/default directories have become contaminated - and are best replaced with a known clean version.

You can do this by downloading a clean build of Magento and replacing your directories as necessary. Via SSH you can do this:

cd /home/path/public_html/
mkdir clean_mage
cd clean_mage
MAGENTO_VERSION=1.7.0.0
wget -O magento.tgz  http://www.magentocommerce.com/downloads/assets/$MAGENTO_VERSION/magento-$MAGENTO_VERSION.tar.gz
tar xvfz magento.tgz
cd /home/path/public_html/app/design/frontend
mv base{,.tmp}
cp -par /home/path/public_html/clean_mage/magento/app/design/frontend/base .
cd /home/path/public_html/skin/frontend
mv base{,.tmp}
cp -par /home/path/public_html/clean_mage/magento/skin/frontend/base .

You can also take the opportunity to diff the two directories if you want to verify any changes.

diff -r base base.tmp

NB. This method will cause more errors during the process, as module dependency dictates the existence of specific files. Unfortunately, its par for the course.

---

Disable local modules

By default, Magento defines the PHP include path to load classes in the following order

Local > Community > Core

If a file is in Local - load it and do no more.
If a file is in community - load it and do no more.
If a file can't be found anywhere else - load it from the core.

Again, rather than disable modules via the Magento admin panel, it is more practical to do this at a file level.

Typically, to disable a module the "proper" way, you would edit the respective ./app/etc/modules/MyModule.xml file and set <active>false</active> - however, this doesn't actually prevent a class from loading.

If another class extends a given class in a module (ignoring any Magento dependency declarations), it will still be loaded - regardless of whether the extension is disabled or not.

So again, the best means to disable an extension is to rename the directory.

Begin by disabling local

Just rename the directory via FTP, or use the following SSH command

mv ./app/code/local{,.tmp}

Then disable community

mv ./app/code/community{,.tmp}

If the issue is resolved from either

Then it is a case of understanding which module in particular the error stemmed from. As with the example given above for the package diagnosis, the same process applies.

So restore the X directory and attempt the following, testing between each.

Essentially, the process is to gradually enable directories (modules) one-by-one until the error re-occurs

1. Rename all the modules in the directory to .tmp (for the SSH users ls | xargs -I {} mv {} {}.tmp or rename 's/^/.tmp/' *)
2. Gradually enable each module one-by-one, by removing .tmp from the file name

If the issue is not resolved

Then it is possible the core itself is contaminated. The main Magento PHP core consists of

./app/code/core
./lib

So again, rename these directories and copy in a clean variant. Assuming you already downloaded a clean version of Magento as above, via SSH, you can do this:

cd /home/path/public_html/app/code
mv core{,.tmp}
cp -par /home/path/public_html/clean_mage/magento/app/code/core .

Then if the issue still isn't resolved, replace the lib directory too

cd /home/path/public_html
mv lib{,.tmp}
cp -par /home/path/public_html/clean_mage/magento/lib .

At this point, your Magento store will be nothing more than a vanilla installation with a modified database.

Some models are actually still stored in the database (Eg. order increment) - so at this point, it becomes a case of manually making those edits. So far, all the steps above have been reversible with no lasting damage. But if we were in import a clean Magento database too - it could prove irreversible (short of restoring a backup).

---

The guide above serves to get you on your way to identifying an error; not to fixing the resultant error.

^{Content willingly sourced from www.sonassi.com/knowledge-base/magento-debug-process and www.sonassi.com/knowledge-base/stop-magento-permissions-errors-permanently}

Answer 2

As requested on Twitter and discussed on Meta I'll start here a debugging tutorial for non-devs.

First I think (even thou magento tries to engage this) Magento is too complex for a merchant without developer/development team. But if you are brave and want to try it, we are giving our best here to help you. I think for some questions is the border between "how can I do this?" and "please make my work, I'm too stupid to google this" is a quite fine line. I understand that it is often hard, to google thinks because you don't know what you are googling for, because you don't know the naming yet. This said, let's collect things everyone with a magento store can do, even thou (s)he is no developers.

A very good answer how to debug magento, when you want to get dirty was already given by Sonassi, but I try to add things and copy what I think is applicable for merchants.

Disclaimer :All directories and files mentioned in this post are relative to the magento root folder, which might be in /var/www but depending on the hosting provider, your so called Document Root can be everywhere, ask your provider, if you don't find your magento!

Development mode

You want to have real errors, not that crappy "an error occurred" page which magento delivers normally.

^{Thanks to fontis.com for this image.}

The reports, mentioned on the page can be found in var/reports/<the_number>

When you activate development mode, magento raises real error, these errors can especially leak credentials, like the ones for the database! So, think before you turn it on on production servers!

Open your index.php file in the root folder of magento, depending on the version, you find these lines around line 73:

if (isset($_SERVER['MAGE_IS_DEVELOPER_MODE'])) {
    Mage::setIsDeveloperMode(true);
}

#ini_set('display_errors', 1);

To active now the mode, you have to change these lines.

If you know your IP address (most people get a new one every 24 hours, at least in Germany), google helps you here :

Your public IP address is 87.138.100.68

if (isset($_SERVER['MAGE_IS_DEVELOPER_MODE']) 
    || $_SERVER['REMOTE_ADDR'] == 'my.ip.add.ress'
) {
    Mage::setIsDeveloperMode(true);
    ini_set('display_errors', 1);
}

If you don't know your ip for whatever reasons, you can show errors for everyone.

#if (isset($_SERVER['MAGE_IS_DEVELOPER_MODE']) || true) {
  Mage::setIsDeveloperMode(true);
#}
ini_set('display_errors', 1);

Logging

Magento logs a lot of stuff into two files:

• var/log/exception.log
• var/log/system.log

Exceptions are logged always. The system log needs to be enabled in the backend:

System > Configuration > Developer > Log

Set Enabled to Yes and you see more errors and debug messages in system.log and in exception.log

Is it a theme problem?

You have your own theme, this is configured in backend here:

System > Configuration > Design

^{Thanks to kb.magenting.com for the image}

Here you can configure the package and the theme. If you want to try to reproduce the error in the default theme, remove everything from the input fields. Then click save and you see the standard magento theme as in the demo shop, if you have a shop before 1.8 you can find a screen-shot in the Magento Community Edition User Guide

If you can not reproduce the problem in the default theme, your theme is broken, please contact the theme vendor. We don't give support for third party themes, especially the commercial ones.

What now?

You found a real error, one can reproduce, it is reproducible in the default theme? Great, please open a question, and we are giving our best to help.

In the question:

• describe what you are doing
• what error is raised
• is anything in the log files?
• maybe a screen-shot of the error

Answer 3

1. First of all you should enable Developer mode
2. You may also enable to display errors in index.php:ini_set('display_errors', 1);
3. Compile xDebug extension with any smart IDE(PhpStrom/eclipse)
4. Disable the custom and 3rd parties module
5. Review your exception and error log, resolve listed errors on exception log
6. Check the curl and mcrypt extension must be loaded on your server
7. Check the Folder and files permissions chown -R sonassi:apache /home/path/public_html/ find /home/path/public_html/ -type d -exec chmod 775 {} \; find /home/path/public_html/ -type f -exec chmod 664 {} \;
8. Update the media and var directory permission 0777 if not set
9. Start IDE(phpstrom), then set the debugger start points on index.php 10.Press F8 and go next until you got error

For using above steps you should get errors definitely.

Answer 4

Debug Backtrace

This is the good function to debug the function call in magento.

Add this function in includes/config.php or create new file and put your all common used php functions.

function back_trace($exit = true) {
  $call_back_methods = '';
  $call_back_methods .= '';
  $call_back_methods .= 'S.N.Function NameLine NumberFile Name';
  
  $counter = 1;
  foreach (debug_backtrace() as $index => $data) {
    //if (0 == $index) continue;
    
    $call_back_methods .= '' . $counter++ . '';
    $call_back_methods .= '' . $data['function'] . '';
    $call_back_methods .= '' . $data['line'] . '';
    $call_back_methods .= '' . $data['file'] . '';
  }
  
  $call_back_methods .= '';
  
  print $call_back_methods;
  
  if (true == $exit) exit;
}

OutPut will be