How to Read PrestaShop Error Logs Like a Developer

Why PrestaShop Error Logs Matter

Every PrestaShop store generates errors. Some are harmless notices that never affect your customers. Others are critical failures that bring your entire checkout to a halt. The difference between a store owner who spends days waiting for support and one who fixes problems in minutes often comes down to a single skill: reading error logs.

Error logs are the diagnostic output of your server and your PrestaShop application. They record every PHP error, every failed database query, every permission problem, and every uncaught exception. When something goes wrong, the answer is almost always sitting in a log file. The challenge is knowing where to look, what to look for, and how to interpret what you find.

This guide covers the complete landscape of PrestaShop error logging. You will learn where every type of log lives, how to enable detailed error reporting, how to read stack traces, and how to use command-line tools to find the needle in the haystack. Whether you are debugging a white screen of death or tracking down an intermittent checkout failure, this is the knowledge you need.

Where PrestaShop Logs Live

PrestaShop generates logs at multiple levels, and each level has its own log files. Understanding which log to check first saves enormous amounts of time.

PrestaShop Application Logs (var/logs)

Starting with PrestaShop 1.7, the application uses the Symfony framework for its back office and core routing. Symfony writes its own logs to the var/logs/ directory in your PrestaShop root. You will find files named according to the current environment:

var/logs/dev.log contains logs when PrestaShop runs in development mode. This file is extremely verbose and records everything from routing decisions to database queries. It can grow to hundreds of megabytes quickly.

var/logs/prod.log contains logs from production mode. This file is much less verbose by default, recording only warnings and errors. This is the file you should check first when something breaks on a live store.

These log files follow the Monolog format, which is the standard logging library in Symfony. Each line includes a timestamp, the log channel (like request, security, or doctrine), the severity level, and the message. A typical entry looks like this:

[2024-03-15 14:22:33] request.CRITICAL: Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for GET /admin/nonexistent" at /var/www/html/vendor/symfony/http-kernel/EventListener/RouterListener.php line 136

The severity levels, from least to most severe, are: DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, and EMERGENCY. When troubleshooting, filter for ERROR and CRITICAL first.

PHP Error Log

PHP itself maintains an error log that is separate from PrestaShop's application logs. This log catches errors that happen before PrestaShop's logging framework initializes, or errors in code that does not use the Symfony logger. The location of this file depends on your server configuration.

On most Linux servers with Apache, the PHP error log is at /var/log/php_errors.log or /var/log/php/error.log. On shared hosting with cPanel, it is often at /home/username/logs/error.log or in the public_html directory as error_log.

You can find the exact location by checking your PHP configuration. Create a temporary PHP file with phpinfo(); and look for the error_log directive. Alternatively, run php -i | grep error_log from the command line.

PHP error logs capture fatal errors, parse errors, warnings, and notices. A fatal error entry typically looks like this:

[15-Mar-2024 14:22:33 UTC] PHP Fatal error: Uncaught Error: Class 'SomeModule\SomeClass' not found in /var/www/html/modules/somemodule/somemodule.php:45

Web Server Logs (Apache and Nginx)

Your web server maintains its own set of logs that are independent of PHP and PrestaShop. These logs are essential for diagnosing 500 errors, 404 errors, and performance issues.

Apache logs are typically found at:

/var/log/apache2/error.log for the error log on Debian and Ubuntu systems.
/var/log/httpd/error_log for the error log on CentOS and RHEL systems.
/var/log/apache2/access.log for the access log, which records every HTTP request.

Nginx logs are typically found at:

/var/log/nginx/error.log for the error log.
/var/log/nginx/access.log for the access log.

If your site uses a virtual host configuration, the logs might be in a site-specific location defined by the ErrorLog (Apache) or error_log (Nginx) directive in your virtual host file.

Web server error logs capture issues like permission denied errors when PHP tries to write to a directory, configuration syntax errors after an .htaccess change, and proxy timeout errors if you are running PHP-FPM behind Nginx. These are the logs to check when you see a generic 500 Internal Server Error with no details in the PHP or PrestaShop logs.

PrestaShop Legacy Logs (Back Office)

PrestaShop also maintains a log viewer within the back office under Advanced Parameters > Logs. This interface shows log entries stored in the ps_log database table. These logs capture events that PrestaShop explicitly records, such as failed login attempts, module installation errors, and email sending failures.

While the back office log viewer is convenient, it has significant limitations. It does not capture PHP errors, web server errors, or most fatal errors that prevent the page from loading. Consider it a supplement to the file-based logs, not a replacement.

Enabling Debug Mode in PrestaShop

By default, PrestaShop runs in production mode and hides detailed error messages from visitors. This is correct for a live store, but it makes debugging nearly impossible. When something breaks, your first step should be enabling debug mode.

Method 1: The defines.inc.php File

Open the file config/defines.inc.php and look for the line that sets _PS_MODE_DEV_. Change it from false to true:

define('_PS_MODE_DEV_', true);

This single change has several effects. PHP error reporting is set to its maximum level, showing all errors, warnings, and notices. Smarty template caching is disabled, so template changes appear immediately. The Symfony profiler toolbar appears at the bottom of back office pages. And most importantly, error details are displayed on screen instead of showing a generic error page.

Method 2: The Debug Profiling Mode

For deeper analysis, you can also enable profiling. In the same file, set:

define('_PS_DEBUG_PROFILING_', true);

This adds detailed timing and memory usage information to the bottom of every page, showing you which hooks take the longest, which modules consume the most memory, and how many database queries each page generates. This is invaluable for performance debugging but should never be left on in production.

Security Warning

Debug mode exposes sensitive information including file paths, database credentials in stack traces, and internal application structure. Never leave debug mode enabled on a production store that is accessible to the public. If you need to debug a live store, consider restricting debug mode to your IP address by wrapping the define in an IP check, or use a staging environment.

Reading Stack Traces

When PrestaShop encounters a fatal error or uncaught exception in debug mode, it displays a stack trace. A stack trace is a snapshot of the call chain that led to the error, reading from the point of failure back to the original entry point. Learning to read stack traces is the single most valuable debugging skill you can develop.

Anatomy of a Stack Trace

A typical PrestaShop stack trace looks like this:

PHP Fatal error: Uncaught TypeError: Argument 1 passed to Product::getProductProperties() must be of the type int, null given, called in /var/www/html/classes/Product.php on line 4523

Stack trace:
#0 /var/www/html/classes/Product.php(4523): Product::getProductProperties(NULL, Array)
#1 /var/www/html/modules/somemodule/somemodule.php(127): Product::getProductProperties(1, Array)
#2 /var/www/html/classes/Hook.php(523): SomeModule->hookDisplayHome(Array)
#3 /var/www/html/classes/Hook.php(460): Hook::coreCallHook(Object(SomeModule), 'hookDisplayHome', Array)
#4 /var/www/html/classes/Hook.php(408): Hook::exec('displayHome', Array)

Read the stack trace from top to bottom. The first line tells you what went wrong: a function expected an integer but received null. The #0 line tells you where the error occurred. The #1 line tells you what called the code at #0. The #2 line tells you what called #1, and so on.

In this example, the chain is clear: PrestaShop executed the displayHome hook, which called the hookDisplayHome method in SomeModule, which called Product::getProductProperties() with a null value where an integer was expected. The bug is in the module at line 127, where it passes an incorrect value.

Finding the Relevant Frame

Stack traces in PrestaShop can be long, sometimes 20 or 30 frames deep. The key is finding the frame that contains your code or the module causing the problem. Look for paths containing /modules/ or /themes/ because these are the most likely sources of bugs. Frames that reference /classes/, /src/, or /vendor/ are core PrestaShop or third-party library code, which is less likely to be the source of the problem unless you have modified core files.

Common PrestaShop Error Patterns

After reading thousands of PrestaShop error logs, certain patterns emerge repeatedly. Recognizing these patterns lets you diagnose problems in seconds instead of hours.

Class Not Found Errors

PHP Fatal error: Uncaught Error: Class 'ModuleName\ClassName' not found

This means the autoloader cannot find the specified class. Common causes include: a missing vendor/autoload.php file (the module needs composer install), a mismatched namespace declaration, a file that was not included in the module ZIP during installation, or a case sensitivity issue on Linux servers where ClassName.php and classname.php are different files.

Permission Denied Errors

Warning: file_put_contents(/var/www/html/var/cache/prod/some_file): failed to open stream: Permission denied

These occur when the web server user (usually www-data on Debian/Ubuntu or apache on CentOS) does not have write permission to a file or directory. Fix this by correcting ownership: chown -R www-data:www-data var/cache/ and permissions: chmod -R 775 var/cache/.

Memory Limit Errors

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 65536 bytes)

The number 134217728 bytes equals 128MB, which is the default PHP memory limit. PrestaShop recommends at least 256MB. Increase it in your php.ini file: memory_limit = 512M. If the error persists even with high memory limits, the code likely has a memory leak, often caused by loading too many products or categories in a single query without pagination.

Database Connection Errors

Link to database cannot be established: SQLSTATE[HY000] [2002] Connection refused

This means PrestaShop cannot connect to the MySQL server. Check that the database server is running, that the credentials in app/config/parameters.php are correct, and that the database host is reachable from the web server.

Smarty Template Errors

SmartyException: Unable to load template file 'module:somemodule/views/templates/hook/display.tpl'

The template file is missing, misspelled, or in the wrong directory. Verify the file exists at the expected path and that the filename matches exactly, including case.

CSRF Token Errors

Invalid token. Please try to log in again.

This appears in the back office when a form submission includes an expired or missing security token. It typically happens when a session expires during a long editing session, when multiple tabs are open to the same admin page, or when a module generates its form URLs incorrectly.

Using grep to Find Errors

When log files are large, scrolling through them manually is impractical. The grep command is your best friend for finding relevant entries quickly.

Basic Error Searching

To find all fatal errors in the PHP error log:

grep 'Fatal error' /var/log/php_errors.log

To find errors from a specific module:

grep 'somemodule' /var/www/html/var/logs/prod.log

To find errors from today only (assuming date format in the log):

grep '2024-03-15' /var/www/html/var/logs/prod.log | grep 'ERROR\|CRITICAL'

Advanced Filtering

To see errors with surrounding context (3 lines before and after each match):

grep -C 3 'Fatal error' /var/log/php_errors.log

To count how many times each unique error occurs:

grep 'Fatal error' /var/log/php_errors.log | sort | uniq -c | sort -rn | head -20

This pipeline sorts the errors, counts duplicates, sorts by count in descending order, and shows the top 20. This is incredibly useful for identifying the most frequent errors that need attention first.

To search across multiple log files simultaneously:

grep -r 'Fatal error' /var/log/ --include='*.log'

The -r flag searches recursively, and --include limits the search to files with the .log extension.

Real-Time Log Monitoring with tail -f

When you are actively debugging a problem, you need to see errors as they happen. The tail -f command follows a log file in real time, displaying new entries as they are written.

Basic Real-Time Monitoring

To watch the PrestaShop production log in real time:

tail -f /var/www/html/var/logs/prod.log

To watch the PHP error log:

tail -f /var/log/php_errors.log

To watch multiple log files at once:

tail -f /var/www/html/var/logs/prod.log /var/log/php_errors.log /var/log/apache2/error.log

Filtered Real-Time Monitoring

To watch only error-level entries in real time, combine tail with grep:

tail -f /var/www/html/var/logs/prod.log | grep --line-buffered 'ERROR\|CRITICAL'

The --line-buffered flag is important here. Without it, grep buffers its output and you may not see matches immediately.

To highlight specific keywords while showing all output:

tail -f /var/www/html/var/logs/prod.log | grep --color=always -E 'ERROR|CRITICAL|$'

This highlights ERROR and CRITICAL in color while still displaying all lines.

The Debugging Workflow

The most effective debugging workflow combines real-time monitoring with active testing. Open one terminal window with tail -f running on the relevant log files. In your browser, reproduce the action that causes the error. Watch the terminal for new log entries that appear at the exact moment you trigger the problem. This approach eliminates guesswork and shows you precisely what happens when the error occurs.

Log Rotation and Management

Log files grow continuously and can consume all available disk space if left unmanaged. Most Linux servers use logrotate to manage this automatically, but PrestaShop's own logs in var/logs/ may not be included in the default logrotate configuration.

Understanding Logrotate

The logrotate utility runs daily (usually via cron) and handles log file rotation, compression, and deletion. Configuration files live in /etc/logrotate.d/. Apache and Nginx log rotation is typically configured out of the box.

For PrestaShop's var/logs directory, you may need to create a custom logrotate configuration:

/var/www/html/var/logs/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 www-data www-data
}

This rotates logs daily, keeps 14 days of history, compresses old logs, and creates new log files with correct permissions.

Manual Log Cleanup

If a log file has grown extremely large and you need to clear it without losing the file handle (important if a process is actively writing to it):

truncate -s 0 /var/www/html/var/logs/prod.log

Do not delete the file and recreate it, because any process that has the file open will continue writing to the deleted file's inode until it is restarted. The truncate approach clears the contents while preserving the inode.

Understanding PrestaShop-Specific Error Contexts

PrestaShop errors often come with context that is unique to the platform. Understanding this context helps you locate and fix problems faster.

Hook-Related Errors

When an error occurs inside a hook, the stack trace will include references to Hook::exec() and Hook::coreCallHook(). The hook name tells you exactly when in the page rendering process the error occurs. For example, displayHome errors happen on the homepage, actionValidateOrder errors happen during checkout, and displayBackOfficeHeader errors happen when loading any back office page.

If a hook error crashes a page, you can temporarily disable the offending module from the database:

UPDATE ps_module SET active = 0 WHERE name = 'somemodule';

This lets you access the back office to properly diagnose and fix the issue.

Override Conflicts

PrestaShop's override system allows modules to extend core classes, but conflicts arise when two modules override the same class. The error typically appears as a method signature conflict or an unexpected behavior change. Check the override/ directory to see which overrides are active, and check the cache/class_index.php file which maps classes to their override files. Deleting this cache file forces PrestaShop to regenerate the override map.

Cache-Related Errors

Many PrestaShop errors are caused by stale cache files. If you see errors that do not match the current code (for example, an error referencing a line number that does not exist in the file), the cache is likely outdated. Clear it by deleting the contents of var/cache/prod/ and var/cache/dev/. On PrestaShop 1.6, clear cache/smarty/compile/ and cache/smarty/cache/ instead.

Module Installation and Upgrade Errors

Module installations can fail silently, leaving the module in a partially installed state. Check var/logs/prod.log for entries during the installation timestamp. Common issues include missing database tables (the module's install() method SQL failed), missing hooks (the registerHook() call failed), and duplicate entry errors in the ps_authorization_role table when reinstalling a module that was not fully uninstalled.

Building a Debugging Checklist

When you encounter a PrestaShop error, follow this systematic checklist to find the cause efficiently:

First, identify the error type. Is it a white screen (500 error), a specific error message, a broken layout, or unexpected behavior? Each type points to different log files.

Second, check the most specific log first. For PHP errors, check the PHP error log. For HTTP errors, check the web server error log. For application errors, check var/logs/prod.log.

Third, enable debug mode if the logs do not reveal enough information. Change _PS_MODE_DEV_ to true and reproduce the error.

Fourth, use tail -f on the relevant logs and reproduce the error in your browser. This gives you a real-time view of exactly what happens.

Fifth, read the stack trace from top to bottom. Find the frame that references your module or theme code. That is where the fix needs to happen.

Sixth, search for the error message in PrestaShop's GitHub issues and forums. Chances are good that someone has encountered and solved the same problem before.

Seventh, after applying a fix, clear all caches and monitor the logs to confirm the error is gone. A fix that does not produce a clean log is not a complete fix.

Summary

Reading PrestaShop error logs is not a mysterious art reserved for senior developers. It is a practical skill built on knowing where logs live, how to filter them, and how to interpret what they contain. The logs at var/logs/, the PHP error log, and the web server error log each serve a different purpose and together give you a complete picture of any problem. Enabling debug mode gives you detailed error messages. Stack traces show you the exact chain of function calls that led to the failure. Tools like grep and tail -f make it possible to find and monitor errors efficiently even in large, busy log files. Master these techniques and you will solve problems faster, with less frustration, and with much less dependence on external support.

For more details, read our guide: Debugging PrestaShop: The Complete Developer Toolkit.