PrestaShop Troubleshooting Overview | Blue Frog Docs

PrestaShop Troubleshooting Overview

Comprehensive troubleshooting guide for PrestaShop issues including performance problems, tracking errors, and common platform-specific challenges.

PrestaShop Troubleshooting Overview

This troubleshooting guide helps you diagnose and resolve common PrestaShop issues related to performance, tracking, modules, and platform-specific challenges.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

Platform Health

  • PrestaShop Version: Check if running latest stable version
  • PHP Version: Verify PHP version meets PrestaShop requirements
  • Server Resources: Check CPU, memory, disk space availability
  • Error Logs: Review PrestaShop and server error logs
  • Cache: Clear all caches (Smarty, PrestaShop, browser)
  • Debug Mode: Temporarily enable for detailed error messages

Module Issues

  • Module Conflicts: Disable recently installed modules
  • Module Compatibility: Verify module PrestaShop version compatibility
  • Hook Registration: Check if modules properly registered to hooks
  • Module Updates: Ensure all modules are up-to-date
  • Override Conflicts: Check for class/controller override conflicts

Database & Performance

  • Database Size: Check for excessive table growth
  • Indexes: Verify database indexes are intact
  • Slow Queries: Identify slow-running database queries
  • Image Optimization: Check for unoptimized product images
  • Third-Party Scripts: Audit external scripts loading

Common Issue Categories

Performance Issues

PrestaShop stores can suffer from performance degradation over time.

Common Symptoms:

Quick Fixes:

  1. Enable PrestaShop Smarty cache
  2. Enable CSS/JS compression and minification
  3. Optimize images (WebP format, lazy loading)
  4. Upgrade to PHP 8.x for performance boost
  5. Implement full page caching (Varnish)

Detailed Guides:

Tracking & Analytics Issues

Analytics and marketing pixel tracking problems are common.

Common Symptoms:

  • Events not firing in GA4/Meta Pixel
  • Duplicate tracking events
  • Missing ecommerce data
  • Purchase events not recording
  • Data layer errors

Quick Checks:

  1. Verify tracking code loaded (check page source)
  2. Check browser console for JavaScript errors
  3. Clear PrestaShop cache and regenerate templates
  4. Test with ad blockers disabled
  5. Use browser extensions (Meta Pixel Helper, GA Debugger)

Detailed Guide:

Module Conflicts

PrestaShop's modular architecture can lead to conflicts.

Common Symptoms:

  • White screen of death (WSOD)
  • Module won't activate
  • Module settings not saving
  • Features stop working after module install
  • JavaScript errors from modules

Resolution Steps:

  1. Identify Conflicting Module:

    # Disable all modules via database
mysql -u username -p
USE prestashop_db;
UPDATE ps_module SET active = 0;

  2. Re-enable One by One:

    • Enable modules individually via Back Office
    • Test functionality after each activation
    • Note which module causes the issue

  3. Check Override Conflicts:

    # List all overrides
ls -la override/classes/
ls -la override/controllers/

  4. Review Module Hooks:

    • Check if multiple modules hook into same position
    • Adjust module hook priority if needed
    • Disable conflicting hooks

Theme Issues

Theme-related problems after updates or customizations.

Common Symptoms:

  • Broken layout after theme update
  • Missing CSS/JS files
  • Template not found errors
  • Custom code disappeared after update

Prevention & Fixes:

  1. Use Child Themes:

    # Create child theme directory
themes/custom-theme/
├── config/
│   └── theme.yml
└── templates/
    └── (overridden templates)

  2. Document Customizations:

    • Keep changelog of template modifications
    • Use version control (Git)
    • Backup before updates

  3. Clear Compiled Smarty Templates:

    rm -rf var/cache/dev/*
rm -rf var/cache/prod/*

  4. Regenerate Assets:

    Back Office > Advanced Parameters > Performance > Clear Cache

Checkout & Cart Issues

Problems during checkout process affect conversions.

Common Issues:

Cart Not Updating:

// Check for JavaScript errors
console.log(prestashop);

// Verify AJAX endpoint
prestashop.urls.base_url

Checkout Steps Not Progressing:

  • Check payment module activation
  • Verify shipping carrier configuration
  • Review checkout validation errors
  • Check for JavaScript conflicts

Product Out of Stock But Shows Available:

  • Clear PrestaShop cache
  • Regenerate stock availability
  • Check StockAvailable table in database

Multi-Store Issues

Multi-store setups introduce additional complexity.

Common Challenges:

Wrong Store Context:

// Verify current shop context
var_dump(Shop::getContext());
var_dump(Shop::getContextShopID());

Configuration Not Applying:

  • Check if configuration is shop-specific or global
  • Verify shop context when saving settings
  • Review Configuration table for shop_id

URLs Not Working:

  • Check .htaccess rules
  • Verify shop domain and URL settings
  • Ensure SSL settings correct per shop

Database Issues

Database problems impact entire store.

Common Issues:

Corrupted Tables:

-- Check for corrupted tables
CHECK TABLE ps_product;
CHECK TABLE ps_cart;
CHECK TABLE ps_orders;

-- Repair if corrupted
REPAIR TABLE ps_product;

Large Database Size:

-- Find largest tables
SELECT
    table_name AS 'Table',
    ROUND(((data_length + index_length) / 1024 / 1024), 2) AS 'Size (MB)'
FROM information_schema.TABLES
WHERE table_schema = 'prestashop_db'
ORDER BY (data_length + index_length) DESC
LIMIT 10;

Orphaned Records:

-- Find orphaned cart products
SELECT COUNT(*) FROM ps_cart_product cp
LEFT JOIN ps_cart c ON cp.id_cart = c.id_cart
WHERE c.id_cart IS NULL;

-- Clean up old carts (older than 30 days)
DELETE FROM ps_cart WHERE date_add < DATE_SUB(NOW(), INTERVAL 30 DAY);

Debugging Tools & Techniques

Enable Debug Mode

Method 1: Edit config/defines.inc.php

// Enable debug mode
if (!defined('_PS_MODE_DEV_')) {
    define('_PS_MODE_DEV_', true);
}

Method 2: Via Back Office

Advanced Parameters > Performance > Debug Mode > Yes

What Debug Mode Shows:

  • Detailed PHP errors
  • SQL query execution times
  • Smarty template compilation errors
  • Hook execution order
  • Memory usage

Check Error Logs

PrestaShop Error Logs:

# View recent errors
tail -f var/logs/$(date +%Y%m%d)_exception.log

# Search for specific errors
grep "Fatal error" var/logs/*.log

Server Error Logs:

# Apache
tail -f /var/log/apache2/error.log

# Nginx
tail -f /var/log/nginx/error.log

# PHP-FPM
tail -f /var/log/php8.1-fpm.log

Browser Developer Tools

Console Tab:

  • JavaScript errors
  • AJAX request failures
  • Tracking pixel errors

Network Tab:

  • Failed resource loads
  • Slow requests (> 1s)
  • 404 errors
  • Large file downloads

Performance Tab:

PrestaShop Profiler

Enable Profiler:

Back Office > Advanced Parameters > Performance > Profiling > Yes

What It Shows:

  • Page generation time
  • Database query count and duration
  • Memory usage
  • Loaded modules and hooks
  • Template compilation time

Database Profiling

Enable Slow Query Log:

-- MySQL configuration
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2; -- Log queries > 2 seconds
SET GLOBAL slow_query_log_file = '/var/log/mysql/slow-query.log';

Analyze Slow Queries:

# Use pt-query-digest (Percona Toolkit)
pt-query-digest /var/log/mysql/slow-query.log

PrestaShop-Specific Debugging

Hook Debugging

List All Registered Hooks:

// Create debug file: debug-hooks.php in root
require_once('config/config.inc.php');

$hooks = Hook::getHooks();
foreach ($hooks as $hook) {
    echo $hook['name'] . "\n";

    $modules = Hook::getModulesFromHook($hook['id_hook']);
    foreach ($modules as $module) {
        echo "  - " . $module['name'] . "\n";
    }
}

Check Module Hook Registration:

-- See which hooks a module uses
SELECT h.name, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON hm.id_hook = h.id_hook
JOIN ps_module m ON hm.id_module = m.id_module
WHERE m.name = 'your_module_name'
ORDER BY hm.position;

Override Debugging

List All Active Overrides:

# Check for class overrides
find override/classes/ -type f -name "*.php"

# Check for controller overrides
find override/controllers/ -type f -name "*.php"

Disable Specific Override:

# Temporarily rename override file
mv override/classes/Product.php override/classes/Product.php.disabled

# Clear cache
rm -rf var/cache/*

Cache Debugging

Clear All Caches:

# Via command line
rm -rf var/cache/dev/*
rm -rf var/cache/prod/*
rm -rf var/cache/smarty/*

# Regenerate class index
php bin/console prestashop:update:class-index

# Clear XML cache
rm -rf config/xml/*.xml

Disable Smarty Cache for Debugging:

// In config/smarty.config.inc.php
$smarty->caching = false;
$smarty->compile_check = true;
$smarty->force_compile = true;

Getting Help

PrestaShop Resources

Official Resources:

Community Resources:

  • PrestaShop Stack Exchange
  • r/PrestaShop subreddit
  • PrestaShop Facebook groups
  • Developer Slack/Discord channels

When to Seek Professional Help

Consider hiring a PrestaShop expert when:

  • Critical Production Issues: Store down, revenue impact
  • Complex Customizations: Multi-store, custom modules, API integrations
  • Performance Bottlenecks: Require server-level optimization
  • Security Concerns: Hacking, malware, PCI compliance
  • Migration Projects: Platform upgrade, server migration

Preparing a Support Request

Include These Details:

  1. Environment Information:

    • PrestaShop version
    • PHP version
    • Server type (Apache/Nginx)
    • Hosting provider
    • Active theme and modules

  2. Issue Description:

    • What were you doing when issue occurred?
    • What did you expect to happen?
    • What actually happened?
    • Can you reproduce it consistently?

  3. Error Messages:

    • Full error text (copy-paste, not screenshot)
    • Error logs (recent 50 lines)
    • Browser console errors

  4. Recent Changes:

    • Modules installed/updated
    • Theme modifications
    • PrestaShop upgrades
    • Server changes

  5. Troubleshooting Done:

    • Steps already attempted
    • What worked/didn't work
    • Tests performed

Prevention Best Practices

Regular Maintenance

Weekly:

  • Review error logs
  • Check website uptime and performance
  • Test critical user flows (browse, add to cart, checkout)
  • Verify backup completion

Monthly:

  • Update PrestaShop to latest patch version
  • Update modules to latest versions
  • Review and optimize database
  • Audit enabled modules (disable unused)
  • Check security patches

Quarterly:

  • Full database backup and verification
  • Review server resources and scaling needs
  • Performance audit and optimization
  • Security audit
  • Update PHP version if needed

Development Best Practices

Use Staging Environment:

  • Test all changes before production
  • Mirror production environment
  • Use same PrestaShop/PHP versions

Version Control:

  • Track all custom code with Git
  • Document all modifications
  • Tag production releases

Monitoring:

  • Set up uptime monitoring
  • Configure error alerting
  • Track Core Web Vitals
  • Monitor conversion rates

Next Steps

Explore specific troubleshooting guides:

Performance:

Tracking:

Platform:

↑ Back to top
// SYS.FOOTER