Debug Logs

How do I interpret a debug log?

Debug logs are created by Zen Cart when the PHP interpreter has an error in creating a webpage. These logs are a source of valuable information that can help you resolve the underlying cause of the problem.

By default, log files are created in the /logs folder at the root of your store. Some hosting setups handle this differently - see missing log files if you think this is happening to you.

Reading a Log

A debug-log’s contents can be a little cryptic, here’s part of one created for zc156c, showing the spacing when multiple logs occur on a single page-load:

[25-Mar-2020 17:19:28 Europe/Berlin] Request URI: /zc156c/index.php?main_page=index&cPath=63, IP address: ::1
#1  define() called at [C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php:35]
#2  require_once(C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php) called at [C:\xampp\htdocs\zc156c\includes\modules\require_languages.php:26]
#3  require(C:\xampp\htdocs\zc156c\includes\modules\require_languages.php) called at [C:\xampp\htdocs\zc156c\includes\modules\pages\index\header_php.php:44]
#4  require(C:\xampp\htdocs\zc156c\includes\modules\pages\index\header_php.php) called at [C:\xampp\htdocs\zc156c\index.php:36]
--> PHP Notice: Constant TABLE_HEADING_PRODUCTS already defined in C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php on line 35.

[25-Mar-2020 17:19:28 Europe/Berlin] Request URI: /zc156c/index.php?main_page=index&cPath=63, IP address: ::1
#1  define() called at [C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php:37]
#2  require_once(C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php) called at [C:\xampp\htdocs\zc156c\includes\modules\require_languages.php:26]
#3  require(C:\xampp\htdocs\zc156c\includes\modules\require_languages.php) called at [C:\xampp\htdocs\zc156c\includes\modules\pages\index\header_php.php:44]
#4  require(C:\xampp\htdocs\zc156c\includes\modules\pages\index\header_php.php) called at [C:\xampp\htdocs\zc156c\index.php:36]
--> PHP Notice: Constant TABLE_HEADING_QUANTITY already defined in C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php on line 37.

Each log-entry contains three (3) significant sections (not in this order):

  1. A header
  2. An identification of the specific error.
  3. A ‘back-trace’ of the PHP modules called when the issue occurred.

Log-entry: Header

Each log-entry starts with a line identifying the date and time, the URI and the IP address associated with the log’s creation, e.g. [25-Mar-2020 17:19:28 Europe/Berlin] Request URI: /zc156c/index.php?main_page=index&cPath=63, IP address: ::1.

This information provides you with:

  1. The date and time that the log was created, since your web-server’s file-system time might be different from your store’s time-zone!
  2. The URI used to access the site when the issue arose, e.g. http://example.com/zc156c/index.php?main_page=index&cPath=63. This gives you the link to use to replicate the issue.
  3. The IP address being used to access the site.

Log-entry: Specific Error

Each log-entry ends with a line identifying the specific issue being reported, e.g. --> PHP Notice: Constant TABLE_HEADING_PRODUCTS already defined in C:\xampp\htdocs\zc156c\includes\languages\english\responsive_classic\index.php on line 35.

This information provides you with:

  1. The severity of the issue, one of PHP Notice, PHP Deprecated, PHP Warning or PHP Fatal error.
  2. A text-string describing the error, e.g. Constant TABLE_HEADING_PRODUCTS already defined.
  3. An identification of the line number and PHP module name that was active when the issue was logged.

Log-entry: Back-Trace

The middle portion of each log-entry contains a back-trace (or stack-trace) that identifies the sequence of PHP module ‘calls’ that lead to the issue, starting (#1) with the module for which the issue was logged and ending with the module name (e.g. index.php, for the example above) that started the page’s output. Each line-entry identifies a PHP statement (e.g. define) that was executed from a specific line-number of a specific PHP module.

Let’s examine the back-trace provided by the first log-entry in the example given above.

Calling Module:Line Number PHP Function
/index.php:36 require
/includes/modules/pages/index/header_php.php:44 require
/includes/modules/require_languages.php:26 require_once
/includes/languages/english/responsive_classic/index.php:35 define

How to Fix Common Debug Logs

Many examples of debug logs and how to fix them are shown in PHP Warnings and Deprecated messages after upgrading.

Logs and Versioning

As PHP is improved and enhanced, things that didn’t create a debug log in older PHP versions now do. So if your hoster upgrades your PHP version, you might start seeing new logs.

Every version of Zen Cart that is released fixes a number of debug logs which occurred in prior releases, especially with PHP versions that were released after that version of Zen Cart was released.

So if you’re seeing a lot of logs, and your Zen Cart version is old, and especially if it’s not recent enough for your PHP version, you should upgrade.

Special Logs

Some logs will follow special file naming conventions to make them more easily identifiable. The following prefixes are used:

  • myDEBUG-bounced-email-adm- failure to send email from admin
  • myDEBUG-bounced-email- failure to send email from storefront
  • zcInstallLog_ - log created by the zc_install process.
  • zcDEBUG-* - fatal errors which occurred during the zc_install process

Another kind of special log also exists with the zcInstallLog_ prefix. It tracks the progress of the zc_install operation for debugging. These files are removed upon login to the Admin.

Utilities

The following tools are available for working with debug log files:

  • Log Manager - Automatically remove logs after a certain period of time.

These are for older versions of Zen Cart:

  • Display Log Files - View the contents of the log-files via an admin tool. Built in to Zen Cart since 1.5.7.
  • myDEBUG log Backtrace - shows stack trace when a log is created. Built in to Zen Cart since 1.5.5.
  • Report All Errors - shows more extensive error logging than is done by default in Zen Cart. Built in to Zen Cart since 1.5.7.



Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified August 28, 2024 by Scott Wilson (74684cbe).