PrestaShop Fehlersuche: White Screen, 500-Fehler & häufige Probleme

Die richtige Denkweise bei der Fehlersuche

Etwas funktioniert nicht mehr. Der Instinkt sagt, sofort etwas zu ändern. Widerstehen Sie dem. Wenn Sie mehrere Dinge gleichzeitig ändern, können Sie nicht feststellen, was das Problem behoben hat. Die Methode, die funktioniert: beobachten, isolieren, beheben, überprüfen. Lesen Sie die Fehlermeldung. Prüfen Sie die Logs. Ändern Sie eine Sache. Testen Sie. Wiederholen Sie den Vorgang.

Bevor Sie irgendetwas ändern, erstellen Sie ein Backup. Datenbank-Dump + Dateiarchiv. Falls Ihre Änderung die Situation verschlechtert, brauchen Sie einen Weg zurück.

1. Debug-Modus aktivieren

Der Debug-Modus ist Ihr erstes Werkzeug bei jedem Problem. PrestaShop blendet Fehler standardmäßig aus — gut für Kunden, schlecht für die Fehlersuche.

PrestaShop 1.6 und 1.7

Bearbeiten Sie config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // Change false to true

Dies aktiviert die Fehleranzeige, deaktiviert den Smarty-Cache und setzt error_reporting auf E_ALL. Ab PS 1.7.7 wird zusätzlich die Symfony-Debug-Toolbar am unteren Seitenrand angezeigt.

PrestaShop 8.x und 9.x

Der gleiche defines.inc.php-Ansatz funktioniert, aber PS 8+ liest auch aus .env:

# .env or .env.local
APP_ENV=dev
APP_DEBUG=1

Notfall-Lösung

Wenn der Fehler auftritt, bevor PrestaShop seine Konfiguration lädt, erzwingen Sie die PHP-Fehleranzeige am Anfang der index.php:

ini_set('display_errors', 1);
error_reporting(E_ALL);

Ab PS 1.7.7 aktiviert der Debug-Modus auch die Symfony-Profiler-Toolbar, die jede Datenbankabfrage, Speicherverbrauch, Cache-Treffer/-Fehlschläge und gerenderte Templates anzeigt.

Lassen Sie den Debug-Modus niemals in der Produktionsumgebung aktiviert. Er legt Dateipfade, Datenbankdetails und interne Logik für jeden offen.

2. Weißer Bildschirm (WSOD)

Eine leere weiße Seite bedeutet, dass PHP auf einen schwerwiegenden Fehler gestoßen ist, aber display_errors deaktiviert ist. Der Fehler existiert — er wird nur nicht angezeigt.

Schritt 1: Fehlerprotokoll prüfen

Der Fehler wird immer irgendwo protokolliert: var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), Apache-Fehlerprotokoll oder PHP-Fehlerprotokoll. Bei Shared Hosting: ~/logs/error.log.

Schritt 2: Debug-Modus aktivieren

Wenn die Logs nicht zugänglich sind, aktivieren Sie _PS_MODE_DEV_ und laden Sie die Seite neu.

Schritt 3: PHP-CLI-Prüfung

Wenn die Seite komplett leer ist, testen Sie mit PHP: php -l config/defines.inc.php (Syntaxprüfung) oder php -r "require 'config/config.inc.php';" (Ladetest).

Häufigste Ursachen

• Speicherlimit erschöpft: Erhöhen Sie den Wert in php.ini: memory_limit = 512M (mindestens 256M für PS 1.7+, 512M für PS 8+).
• PHP-Versionskonflikt: PS 1.6 funktioniert nicht mit PHP 7.4+. PS 1.7.0-1.7.6 funktioniert nicht mit PHP 8.0+. PS 9.x erfordert PHP 8.1+.
• Schwerwiegender Fehler in einem Modul: Benennen Sie den Modulordner per FTP um: modules/problem_module zu modules/problem_module_disabled.
• Beschädigter Cache: Löschen Sie alles in var/cache/ (PS 1.7+) oder cache/smarty/compile/ (PS 1.6).
• Defektes Override: Benennen Sie das override/-Verzeichnis vorübergehend um, um zu testen.

3. 500 Internal Server Error

HTTP 500 bedeutet, dass der Server auf eine Bedingung gestoßen ist, die er nicht verarbeiten konnte. Im Gegensatz zum WSOD erreicht dieser Fehler möglicherweise nicht einmal PHP.

.htaccess-Probleme

Die häufigste Ursache. Testen Sie durch vorübergehendes Umbenennen: mv .htaccess .htaccess.bak. Wenn die Seite lädt (mit defekten URLs), ist die .htaccess das Problem.

• mod_rewrite nicht aktiviert: a2enmod rewrite && systemctl restart apache2
• AllowOverride None: Muss AllowOverride All in der Virtual-Host-Konfiguration sein.
• Nicht unterstützte Direktiven: Einige Shared-Hosting-Anbieter blockieren Options oder php_value. Kommentieren Sie Abschnitte aus, bis Sie den Verursacher finden.
• Neu generieren: Shop-Parameter → Traffic & SEO → „.htaccess-Datei generieren“.

Dateiberechtigungen

Verzeichnisse: 755, Dateien: 644, beschreibbare Verzeichnisse (var/cache, img, upload): 775. Niemals 777.

find /path/to/prestashop -type d -exec chmod 755 {} \;
find /path/to/prestashop -type f -exec chmod 644 {} \;

PHP-Limits

memory_limit = 512M
max_execution_time = 300
max_input_vars = 10000
post_max_size = 64M
upload_max_filesize = 64M

max_input_vars wird oft übersehen — PS-Produktseiten mit Varianten überschreiten den Standardwert von 1000.

4. Modulkonflikte

Module sind die häufigste Ursache für Probleme. Zwei Module, die dasselbe tun möchten, werden in Konflikt geraten.

Die Isolationsmethode

1. Deaktivieren Sie alle Drittanbieter-Module über den Modul-Manager.
2. Bestätigen Sie, dass das Problem behoben ist.
3. Aktivieren Sie die Module einzeln nacheinander und testen Sie nach jedem Schritt.

Wenn das Admin-Panel nicht funktioniert, deaktivieren Sie über die Datenbank:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Or rename the folder: mv modules/problem_module modules/problem_module.bak

Override-Konflikte

Zwei Module können nicht dieselbe Klasse überschreiben. Prüfen Sie override/classes/ und override/controllers/. Wenn Sie ein Override manuell entfernen, löschen Sie var/cache/*/class_index.php, um die Neugenerierung zu erzwingen.

Hook-Priorität

Wenn zwei Module denselben Hook verwenden, ist die Ausführungsreihenfolge entscheidend. Passen Sie diese unter Design → Positionen an, oder fragen Sie ps_hook_module ab, um die Ausführungsreihenfolge pro Hook zu sehen.

Wenn Sie einen Modulkonflikt an einen Entwickler melden, geben Sie folgendes an: die genaue Fehlermeldung aus dem Log, Ihre PS-Version, PHP-Version, andere aktive Module und Schritte zur Reproduktion.

5. Cache-Probleme

PrestaShop verfügt über mehrere unabhängige Caches. Wenn „Cache leeren“ nicht funktioniert, haben Sie wahrscheinlich den falschen Cache geleert.

Die Cache-Schichten

• Smarty: Kompilierte TPL-Dateien in var/cache/prod/smarty/.
• Symfony: Kompilierte Container, Routen, Übersetzungen in var/cache/prod/.
• OPcache: PHP-Bytecode im Shared Memory — im Dateisystem nicht sichtbar.
• Objekt-Cache: Datenbankabfrage-Cache (dateibasiert oder Redis).
• Browser-Cache: CSS, JS, Bilder auf dem Gerät des Besuchers.

Alles leeren

Admin-Panel: Erweiterte Einstellungen → Leistung → Cache leeren. Wenn das Admin-Panel nicht funktioniert:

# Delete cache directories
rm -rf var/cache/prod/* var/cache/dev/*

# Or use Symfony console (PS 8+/9)
php bin/console cache:clear --env=prod

OPcache

Nach dem Bearbeiten von PHP-Dateien liefert OPcache möglicherweise noch die alte Version. Setzen Sie ihn über eine Web-Anfrage zurück — erstellen Sie eine temporäre Datei mit opcache_reset();, rufen Sie sie im Browser auf und löschen Sie sie anschließend. Ein CLI-Reset leert nur den CLI-Cache, nicht den Web-Cache.

Wenn der Cache „hängt“

Ordnen Sie den Cache der Änderung zu: Template → Smarty, PHP-Code → OPcache, Konfiguration → Symfony, CSS/JS → Browser (Strg+Umschalt+R). Prüfen Sie auch die Berechtigungen von var/cache/, löschen Sie class_index.php, um die Neugenerierung zu erzwingen, und leeren Sie das CDN separat.

Nach jedem Deployment: Symfony-Cache, Smarty-Cache, OPcache (per Web) und CDN-Cache leeren. Wenn Sie auch nur einen davon vergessen, scheint Ihr Deployment „nicht funktioniert“ zu haben.

6. Datenbankprobleme

Datenbankprobleme treten meist nach fehlgeschlagenen Upgrades, unterbrochenen Importen oder Zeitlimit-Überschreitungen auf.

Beschädigte Tabellen

# Check all tables
mysqlcheck -u root -p prestashop_db --check

# Repair (MyISAM only)
REPAIR TABLE ps_product;

# For InnoDB (most modern installs), rebuild in place:
ALTER TABLE ps_product ENGINE=InnoDB;

Fehlende Spalten nach fehlgeschlagenem Upgrade

Fehler: Unknown column 'new_column' in 'field list'. Das Upgrade wurde unterbrochen und hat Tabellen unvollständig hinterlassen.

# Check what columns exist
SHOW CREATE TABLE ps_product\G

# Look for upgrade SQL in install-dev/upgrade/sql/ or install/upgrade/sql/
# Add the missing column manually:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Strukturen vergleichen

Installieren Sie eine frische Kopie Ihrer PS-Version, exportieren Sie beide Strukturen mit mysqldump --no-data und vergleichen Sie sie per Diff, um fehlende Tabellen, Spalten und Indizes aufzudecken.

Hängende Abfragen

Führen Sie SHOW FULL PROCESSLIST aus, um hängende Abfragen zu finden, KILL <id> zum Beenden, und SHOW ENGINE INNODB STATUS zur Überprüfung von Lock-Wartezeiten.

Führen Sie ALTER TABLE niemals während der Geschäftszeiten auf großen Produktionstabellen aus. Das Hinzufügen einer Spalte zu einer Tabelle mit einer Million Zeilen kann sie minutenlang sperren.

7. Theme-Probleme

Fehlende Templates

Fehler: unable to load template file 'module:modulename/...'. PrestaShop sucht zuerst im Theme-Override (themes/your_theme/modules/...), dann im Standard des Moduls. Wenn ein Theme-Override auf eine gelöschte oder umbenannte Datei verweist, erhalten Sie diesen Fehler. Unter Linux sind Dateinamen groß-/kleinschreibungsabhängig.

Smarty-Kompilierungsfehler

Nicht übereinstimmende Tags (jedes {if} braucht ein {/if}), JavaScript-Klammern (JS in {literal}{/literal} einschließen) und Encoding-Probleme (TPL-Dateien müssen UTF-8 ohne BOM sein) sind die üblichen Verursacher.

Fehler beim Laden von Assets

Prüfen Sie die Browser-Konsole (F12 → Netzwerk) auf 404-Fehler. Häufige Ursachen: falsche Pfade in theme.yml, beschädigter CCC-Cache, CDN-Fehlkonfiguration.

Child-Theme-Probleme

Eltern-Theme gelöscht (Child scheitert mit „Invalid theme“), veraltete Template-Overrides nach Updates des Eltern-Themes, oder unvollständige theme.yml im Child-Theme, die dazu führt, dass Module aus Hooks verschwinden.

Prüfen Sie beim Upgrade von PrestaShop das Changelog auf Template-Änderungen. Child-Theme-Overrides von geänderten Templates müssen aktualisiert werden.

8. PHP-Versionskompatibilität

Kompatibilitätsmatrix

* PS 1.7.8 hat teilweise PHP-8.0-Unterstützung — der Kern funktioniert, aber viele Module nicht.

Häufige Upgrade-Fehler

• PHP 7.x → 8.0: TypeError: expects string, null given — PHP 8 ist strikt bei null in strlen(), strpos() usw.
• PHP 8.0 → 8.1: Return type should be compatible — strengere Typen. FILTER_SANITIZE_STRING veraltet.
• PHP 8.1 → 8.2: Dynamische Eigenschaften veraltet.

Wichtig: CLI- und Web-PHP-Version können auf Multi-PHP-Servern unterschiedlich sein. Prüfen Sie immer mit phpinfo() im Browser, nicht nur mit php -v. Vor dem Upgrade: auf einer Staging-Umgebung testen, php -l auf Moduldateien ausführen, Module zuerst aktualisieren.

9. E-Mails werden nicht versendet

• Test über das Admin-Panel: Erweiterte Einstellungen → E-Mail → „Test-E-Mail senden“.
• SMTP-Einstellungen prüfen: Host, Port (587/TLS oder 465/SSL), Benutzername, Passwort.
• Tabelle ps_mail prüfen: Wenn E-Mails hier erscheinen, hat PS sie versendet — das Problem liegt bei der Zustellung.
• PHP mail(): Wenn es fehlschlägt, wechseln Sie zu SMTP — überall zuverlässiger.
• DNS-Einträge: SPF, DKIM und DMARC sind für moderne E-Mail-Zustellung erforderlich.

Vollständiger Leitfaden: PrestaShop E-Mail-Zustellbarkeit.

10. Plötzlicher Leistungseinbruch

Schnelldiagnose

Prüfen Sie den Speicherplatz (df -h), die Serverlast (uptime), MySQL (SHOW FULL PROCESSLIST) und den OPcache-Status. Volle Festplatten lassen alles stillschweigend abstürzen.

Häufige plötzliche Verlangsamungen

• Debug-Modus versehentlich aktiviert: Prüfen Sie zuerst _PS_MODE_DEV_. Das löst mehr „langsamer Shop“-Beschwerden als alles andere.
• Volle Festplatte: MySQL stürzt ab, Caches können nicht schreiben, Logs können nicht rotiert werden.
• Fehlerhafte Modul-Abfrage: Eine nicht indizierte Abfrage auf einer großen Tabelle kann Sekunden pro Seitenaufruf hinzufügen.
• Aufgestapelte Cron-Jobs: Mehrere Import-/Indexer-Skripte laufen gleichzeitig.
• Aufgeblähte Tabellen: ps_connections, ps_log, ps_cart wachsen ohne Wartung endlos.

Vollständiger Leitfaden: PrestaShop Performance-Optimierung.

11. Häufige Fehlermeldungen entschlüsselt

„Class 'SomeClass' not found“

Löschen Sie var/cache/prod/class_index.php (wird automatisch neu generiert), führen Sie composer dump-autoload aus (PS 1.7+), und prüfen Sie unter Linux die Groß-/Kleinschreibung der Dateinamen. Wenn ein Modul nur teilweise gelöscht wurde, bereinigen Sie die Tabellen ps_hook_module und ps_module.

„CSRF token error“ / „Invalid token“

Sitzung abgelaufen (erhöhen Sie session.gc_maxlifetime), mehrere Admin-Tabs (aktualisieren Sie die Seite), Reverse-Proxy entfernt Cookies (Admin vom Caching ausschließen), oder die Serveruhr geht falsch.

„Ajax error“

Öffnen Sie die Entwicklertools (F12) → Netzwerk-Tab. Reproduzieren Sie den Fehler. Finden Sie die fehlgeschlagene Anfrage (rot, Status 500). Der Antwort-Tab zeigt den eigentlichen PHP-Fehler.

„Allowed memory size exhausted“

Setzen Sie memory_limit = 512M in php.ini oder .htaccess. Wenn der Shop ständig mehr benötigt, handelt es sich um einen Speicherleck in einem Modul — verwenden Sie den Symfony-Profiler, um den Verursacher zu finden.

„Duplicate entry for key“

Eine Verletzung einer Unique-Einschränkung. Häufig bei Produktimporten (doppelte Referenzen), Modulinstallationen im Multistore oder dem erneuten Ausführen fehlgeschlagener Upgrades.

„Deprecated: ...“-Flut

Eine Warnung, kein Fehler. Unterdrücken: error_reporting = E_ALL & ~E_DEPRECATED. Besser: Aktualisieren Sie das Modul. Diese Warnungen werden in der nächsten PHP-Version zu schwerwiegenden Fehlern.

12. Notfall-Wiederherstellung

Admin-Passwort zurücksetzen

Für PS 1.6/1.7 (MD5-Hashing):

UPDATE ps_employee SET passwd = MD5(CONCAT(
    (SELECT value FROM ps_configuration WHERE name = '_COOKIE_KEY_'),
    'YourNewPassword!'
)) WHERE email = 'admin@yourdomain.com';

Für PS 8+/9 (bcrypt): Laden Sie ein temporäres PHP-Skript hoch, das config/config.inc.php einbindet, mit PrestaShop\Core\Crypto\Hashing den Hash generiert, ps_employee aktualisiert — und löschen Sie das Skript sofort danach.

Löschen Sie das Reset-Skript sofort nach der Verwendung. Jeder, der es findet, kann jedes Admin-Passwort zurücksetzen.

Defektes Modul deaktivieren

-- Via database
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Via filesystem (more reliable)
mv modules/broken_module modules/broken_module.disabled

Um alle Drittanbieter-Module auf einmal zu deaktivieren, aktualisieren Sie ps_module und setzen Sie active = 0 für alle Einträge, deren Name NICHT in der Liste der nativen PS-Module enthalten ist (ps_banner, ps_categorytree, ps_facetedsearch usw.).

Overrides deaktivieren

// config/defines.inc.php
define('_PS_ALLOW_OVERRIDES_', false);

Aus Backup wiederherstellen

Setzen Sie die Seite offline, stellen Sie die Datenbank wieder her (mysql -u root -p db < backup.sql), stellen Sie die Dateien wieder her, leeren Sie alle Caches (rm -rf var/cache/*), setzen Sie OPcache zurück und überprüfen Sie dann, ob Startseite, Produktseite, Warenkorb, Bestellvorgang und Admin-Panel funktionieren.

Wartungsmodus ohne Admin-Panel

UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SHOP_ENABLE';
UPDATE ps_configuration SET value = 'your.ip' WHERE name = 'PS_MAINTENANCE_IP';

13. Diagnose-Checkliste

Drucken Sie diese aus und arbeiten Sie sie von oben nach unten durch, wenn etwas schiefgeht.

Phase 1: Informationen sammeln

• Was hat sich geändert? Modulinstallation/-update, PS-Update, PHP-Update, Serveränderung, Theme-Bearbeitung?
• Wann genau hat es begonnen? Vergleichen Sie mit Deployment-Logs und Cron-Jobs.
• Wer ist betroffen? Alle Benutzer, bestimmte Browser, nur Admin, nur Front-Office?
• Was ist die genaue Fehlermeldung? Aktivieren Sie den Debug-Modus. Prüfen Sie die Browser-Konsole. Prüfen Sie alle Logs.

Phase 2: Isolieren

• Server: Speicherplatz (df -h), Arbeitsspeicher (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP: Version (php -v), Syntaxprüfung (php -l), Einstellungen (phpinfo())
• Cache: Alle Schichten leeren — Smarty, Symfony, OPcache, Browser. Im Inkognito-Modus testen.
• Module: Kürzlich geänderte deaktivieren. Wenn unklar, alle Drittanbieter-Module deaktivieren und einzeln reaktivieren.
• Theme: Vorübergehend zum Standard-Theme wechseln.
• Datenbank: mysqlcheck, MySQL-Fehlerprotokoll, Tabellenstrukturen vergleichen nach einem Upgrade.
• Berechtigungen: ls -la auf var/cache, var/logs, img, upload.

Phase 3: Beheben und Überprüfen

• Nehmen Sie EINE Änderung auf einmal vor. Testen Sie. Wenn es nicht geholfen hat, machen Sie es rückgängig und versuchen Sie das Nächste.
• Leeren Sie nach jeder Änderung alle Caches.
• Testen Sie gründlich: Startseite, Kategorie, Produkt, Warenkorb, Bestellvorgang, Admin.
• Testen Sie im Inkognito-Modus / einem anderen Browser.
• Deaktivieren Sie den Debug-Modus. Entfernen Sie temporäre Skripte.

Phase 4: Wiederholung verhindern

• Dokumentieren Sie, was passiert ist und was das Problem behoben hat.
• Richten Sie Monitoring ein: Verfügbarkeit, Fehlerprotokolle, Speicherplatz.
• Überprüfen Sie, ob Backups funktionieren. Testen Sie eine Wiederherstellung.

Kurzreferenz

Log-Speicherorte

• PS 1.6: log/ — PS 1.7: var/logs/ — PS 8+/9: var/log/
• Apache: /var/log/apache2/error.log — Nginx: /var/log/nginx/error.log
• MySQL: /var/log/mysql/error.log — PHP: gemäß error_log in php.ini

Wichtige Dateien

• config/defines.inc.php — Debug-Modus, Override-Schalter
• app/config/parameters.php — DB-Zugangsdaten, Secret (PS 1.7+)
• .env / .env.local — Umgebung und Debug (PS 8+)
• .htaccess — URL-Rewriting, PHP-Einstellungen, Sicherheit

Wichtige CLI-Befehle (PS 1.7+)

php bin/console cache:clear --env=prod
php bin/console prestashop:module list
php bin/console prestashop:module enable module_name
php bin/console prestashop:module disable module_name
composer dump-autoload -o

Jede Fehlersuche beginnt auf die gleiche Weise: Prüfen Sie den Fehler, prüfen Sie die Logs, isolieren Sie die Ursache. Die erfahrensten Entwickler merken sich nicht jeden Fehler — sie wissen, wo sie suchen müssen. Dieser Leitfaden gibt Ihnen genau diese Stellen.