PrestaShop weisse Seite nach Core-Update: Wiederherstellungsanleitung

Warum nach PrestaShop-Updates weisse Seiten auftreten

Eine leere weisse Seite, oft als White Screen of Death (WSOD) bezeichnet, ist eines der haeufigsten und alarmierendsten Probleme, mit denen PrestaShop-Shopbetreiber nach der Aktualisierung der Core-Software konfrontiert werden. Sie starten ein Update von 1.7.8.7 auf 1.7.8.8 oder von 8.1.0 auf 8.1.5, der Prozess scheint abzuschliessen, und dann zeigt Ihr gesamter Shop, sowohl Front Office als auch Back Office, nichts ausser einem weissen Bildschirm an. Keine Fehlermeldung, kein teilweiser Inhalt, nur Leere.

Um zu verstehen, warum das passiert, muss man verstehen, was ein PrestaShop Core-Update bewirkt. Der Aktualisierungsprozess ersetzt Hunderte von PHP-Dateien, aendert Datenbanktabellen, regeneriert Klassen-Indizes, leert Caches und fuehrt moeglicherweise Migrations-Queries aus. Jedes Versagen an jedem Punkt dieser Kette kann den Shop in einem inkonsistenten Zustand hinterlassen, in dem PHP auf einen fatalen Fehler stoesst, ihn aber nicht anzeigen kann, weil die Fehlerausgabe im Produktionsmodus deaktiviert ist.

Die haeufigsten Ursachen lassen sich in mehrere Kategorien einteilen: inkompatible Module, die auf entfernte oder geaenderte Core-Klassen verweisen, PHP-Versionsinkompatibilitaeten zwischen der alten und neuen PrestaShop-Version, Override-Dateikonflikte, bei denen benutzerdefinierte Overrides mit geaenderten Core-Dateien kollidieren, unzureichende Serverressourcen, die dazu fuehren, dass das Update mittendrin abgebrochen wird, und fehlgeschlagene Datenbankmigrationen, die Tabellen in einem inkonsistenten Zustand hinterlassen.

Schritt 1: Debug-Modus aktivieren

Die allererste Massnahme bei einer leeren Seite ist, Fehler sichtbar zu machen. PrestaShop unterdrueckt die Fehlerausgabe im Produktionsmodus, um zu verhindern, dass sensible Informationen den Besuchern preisgegeben werden. Sie muessen voruebergehend den Debug-Modus aktivieren, um zu sehen, was tatsaechlich schiefgeht.

Die schnellste Methode ist die Bearbeitung der Datei /config/defines.inc.php. Suchen Sie die Zeile, die _PS_MODE_DEV_ definiert, und aendern Sie sie:

define('_PS_MODE_DEV_', true);

Wenn Sie nicht per FTP oder SSH auf Dateien zugreifen koennen, weil auch Ihr Hosting-Panel unzugaenglich ist, bieten einige Hosting-Anbieter einen Dateimanager ueber ihr Kontrollpanel (cPanel, Plesk, DirectAdmin), der unabhaengig von Ihrer PrestaShop-Installation funktioniert.

In PrestaShop 8.x koennen Sie den Debug-Modus auch ueber die .env-Datei im Stammverzeichnis aktivieren. Aendern Sie APP_ENV=prod zu APP_ENV=dev und setzen Sie APP_DEBUG=1. Dies aktiviert die Symfony-Debug-Toolbar und detaillierte Fehlerseiten.

Laden Sie nach dem Aktivieren des Debug-Modus die Seite neu. Anstelle eines leeren Bildschirms sollten Sie nun eine detaillierte Fehlermeldung mit Dateipfad, Zeilennummer und Stack-Trace sehen. Diese Fehlermeldung ist der Schluessel zur Diagnose und Behebung des Problems.

Schritt 2: Fehlerprotokolle pruefen

Wenn das Aktivieren des Debug-Modus weiterhin eine leere Seite anzeigt (was passieren kann, wenn der Fehler auftritt, bevor PHP ueberhaupt das PrestaShop-Framework laedt), pruefen Sie die Fehlerprotokolle Ihres Servers direkt.

Auf Apache-Servern befindet sich das Fehlerprotokoll typischerweise unter /var/log/apache2/error.log oder /var/log/httpd/error_log. Auf Nginx mit PHP-FPM pruefen Sie /var/log/nginx/error.log und /var/log/php-fpm/error.log (oder /var/log/php8.1-fpm.log, je nach PHP-Version). Auf Shared Hosting sind Fehlerprotokolle normalerweise ueber das Hosting-Kontrollpanel oder in einem logs-Verzeichnis innerhalb Ihres Hosting-Kontos zugaenglich.

PrestaShop pflegt auch eigene Logdateien im Verzeichnis /var/logs/ (PrestaShop 1.7) oder /var/log/ (PrestaShop 8.x). Suchen Sie nach Dateien mit dem aktuellen Datum. Diese Symfony-basierten Logs koennen detaillierte Informationen darueber enthalten, was waehrend des Update-Prozesses schiefgelaufen ist.

Ueberpruefen Sie zusaetzlich das Verzeichnis /log/ im PrestaShop-Stammverzeichnis auf Fehlerprotokolldateien. Einige PrestaShop-Versionen schreiben kritische Fehler hierhin, wenn sie sie nicht auf dem Bildschirm anzeigen koennen.

Haeufige Ursache 1: Inkompatible Module

Module sind die haeufigste Ursache fuer weisse Seiten nach Updates. Ein Modul, das auf PrestaShop 1.7.8.7 perfekt funktionierte, kann den gesamten Shop auf 1.7.8.8 zum Absturz bringen, wenn es interne Core-Klassen oder -Methoden verwendet, die sich im Update geaendert haben.

Die Fehlermeldung sieht typischerweise so aus: Fatal error: Class 'SomeClassName' not found oder Fatal error: Call to undefined method ClassName::methodName() oder Fatal error: Declaration of ModuleClass::hookMethod() must be compatible with CoreClass::hookMethod().

Um dies zu beheben, muessen Sie das problematische Modul identifizieren und deaktivieren. Wenn Sie auf das Back Office zugreifen koennen (manchmal stuerzt nur das Front Office ab), gehen Sie zu Module und deaktivieren Sie kuerzlich installierte oder aktualisierte Module einzeln, bis sich das Problem loest.

Wenn auch das Back Office unzugaenglich ist, deaktivieren Sie Module ueber die Datenbank. Verbinden Sie sich mit Ihrer Datenbank ueber phpMyAdmin oder einen MySQL-Client und fuehren Sie aus:

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

Wenn Sie nicht wissen, welches Modul das Problem verursacht, koennen Sie alle Drittanbieter-Module auf einmal deaktivieren, indem Sie deren active-Spalte auf 0 setzen. Identifizieren Sie zunaechst, welche Module von Drittanbietern stammen, indem Sie das Verzeichnis /modules/ auf Nicht-PrestaShop-Module pruefen. Deaktivieren Sie diese dann gezielt.

Ein aggressiverer Ansatz ist die Umbenennung des Modulverzeichnisses. Benennen Sie beispielsweise /modules/somemodule/ in /modules/somemodule_disabled/ um. PrestaShop kann ein Modul nicht laden, dessen Verzeichnis nicht mit seinem registrierten Namen uebereinstimmt, wodurch es effektiv deaktiviert wird, ohne die Datenbank zu beruehren.

Haeufige Ursache 2: PHP-Versionsinkompatibilitaet

Jede PrestaShop-Version erfordert einen bestimmten PHP-Versionsbereich. PrestaShop 1.7.6 und frueher erfordern PHP 7.1 bis 7.3. PrestaShop 1.7.7 bis 1.7.8 unterstuetzen PHP 7.2 bis 8.0. PrestaShop 8.0 erfordert PHP 7.2 bis 8.1. PrestaShop 8.1 erfordert PHP 8.0 bis 8.2. PrestaShop 9.0 erfordert PHP 8.1 oder hoeher.

Wenn Ihre Hosting-Umgebung waehrend oder neben dem PrestaShop-Update die PHP-Version geaendert hat, koennten Sie auf Syntaxfehler oder veraltete Funktionsaufrufe stossen. Haeufige PHP-Kompatibilitaetsfehler umfassen: Deprecated: Function create_function() is deprecated (PHP 7.2+ mit Code fuer PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ hat die mysql-Erweiterung entfernt) und Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Ueberpruefen Sie Ihre aktuelle PHP-Version durch die phpinfo()-Ausgabe oder durch Ausfuehren von php -v auf der Kommandozeile. Wenn die Version ausserhalb des unterstuetzten Bereichs fuer Ihre PrestaShop-Version liegt, wechseln Sie ueber Ihr Hosting-Kontrollpanel zu einer kompatiblen PHP-Version.

Haeufige Ursache 3: Override-Konflikte

Das Override-System von PrestaShop erlaubt es Modulen und Entwicklern, das Core-Verhalten zu aendern, indem modifizierte Klassendateien im Verzeichnis /override/ platziert werden. Waehrend eines Updates aendern sich die Core-Klassen, aber die Override-Dateien bleiben bestehen. Wenn ein Override auf eine Methodensignatur verweist, die sich geaendert hat, auf eine Eigenschaft, die entfernt wurde, oder auf eine Klasse, die umbenannt wurde, verursacht das Override einen fatalen Fehler.

Die Klassen-Index-Datei unter /var/cache/prod/class_index.php (oder /cache/class_index.php in aelteren Versionen) ordnet Klassennamen ihren Dateispeicherorten zu, einschliesslich Overrides. Ein veralteter oder beschaedigter Klassen-Index kann die falsche Datei fuer eine Klasse laden und so sofortige Abstuerze verursachen.

Um zu testen, ob Overrides das Problem sind, deaktivieren Sie voruebergehend das Override-System. Bearbeiten Sie /config/defines.inc.php und fuegen Sie hinzu oder aendern Sie:

define('_PS_HOST_MODE_', false);

Loeschen Sie dann die Klassen-Index-Datei, um PrestaShop zu zwingen, sie ohne Overrides neu zu generieren. Wenn der Shop nach dieser Aenderung laedt, liegt das Problem in einer Ihrer Override-Dateien.

Um das spezifische problematische Override zu identifizieren, schauen Sie in die Verzeichnisse /override/classes/ und /override/controllers/. Entfernen Sie Override-Dateien einzeln und loeschen Sie nach jeder Entfernung den Klassen-Index, bis Sie die Datei finden, die den Absturz verursacht. Nach der Identifizierung aktualisieren Sie entweder das Override, um es mit der neuen Core-Version kompatibel zu machen, oder entfernen Sie es vollstaendig, wenn es nicht mehr benoetigt wird.

Haeufige Ursache 4: Cache und kompilierte Dateien

PrestaShop generiert kompilierte Smarty-Templates, Symfony-Container-Caches, Klassen-Maps und verschiedene andere gecachte Dateien, die nach einem Update ungueltig werden. Wenn der Update-Prozess diese Caches nicht ordnungsgemaess geleert hat, versucht der Shop, gecachte Dateien zu verwenden, die auf die alte Codestruktur verweisen.

Leeren Sie alle Caches manuell, indem Sie den Inhalt dieser Verzeichnisse loeschen (loeschen Sie den Inhalt, nicht die Verzeichnisse selbst):

/var/cache/prod/ und /var/cache/dev/ fuer den Symfony-Cache. Loeschen Sie alles innerhalb dieser Verzeichnisse. PrestaShop wird sie beim naechsten Seitenaufruf neu generieren.

/cache/smarty/compile/ und /cache/smarty/cache/ fuer Smarty-Template-Caches. Veraltete kompilierte Templates sind eine sehr haeufige Ursache fuer weisse Seiten nach Updates.

/var/cache/prod/class_index.php (oder /cache/class_index.php) fuer die Klassen-Map. Diese Datei muss nach jedem Update neu generiert werden.

Bei PHP-FPM-Setups setzen Sie auch OPcache zurueck. OPcache speichert kompilierten PHP-Bytecode im Arbeitsspeicher und kann den alten Code ausliefern, selbst nachdem Dateien ersetzt wurden. Starten Sie den PHP-FPM-Dienst neu, oder erstellen Sie, falls das nicht moeglich ist, eine kleine PHP-Datei, die opcache_reset() aufruft, und greifen Sie ueber Ihren Browser darauf zu.

Haeufige Ursache 5: Fehlgeschlagene Datenbankmigrationen

PrestaShop-Updates enthalten oft Datenbankschema-Aenderungen: neue Spalten, geaenderte Indizes, neue Tabellen oder Datenmigrationen. Wenn der Update-Prozess unterbrochen wurde (Timeout, Speicherlimit, Verbindungsabbruch), kann sich die Datenbank in einem teilweise migrierten Zustand befinden.

Pruefen Sie in der PrestaShop-Datenbank die Tabelle ps_configuration und suchen Sie den Wert PS_VERSION_DB. Wenn dieser Wert nicht mit der Version der Dateien auf der Festplatte uebereinstimmt, wurde das Update nicht ordnungsgemaess abgeschlossen. PrestaShop kann versuchen, die Migrationen beim naechsten Laden erneut auszufuehren, oder es kann einfach fehlschlagen.

Fehlgeschlagene Datenbankmigrationen sind ohne Backup am schwierigsten zu beheben. Wenn Sie ein Datenbank-Backup von vor dem Update haben, ist die Wiederherstellung und erneute Durchfuehrung des Updates oft der sicherste Weg. Wenn Sie kein Backup haben, muessen Sie moeglicherweise die fehlenden SQL-Migrationsdateien manuell anwenden, die im Verzeichnis /install/upgrade/sql/ zu finden sind.

Schritt-fuer-Schritt-Wiederherstellungsverfahren

Befolgen Sie diese Reihenfolge bei der Wiederherstellung nach einer weissen Seite nach einem Core-Update. Die Reihenfolge ist wichtig, weil jeder Schritt entweder das Problem behebt oder eine moegliche Ursache ausschliesst.

Schritt 1: Aktivieren Sie den Debug-Modus in /config/defines.inc.php, indem Sie _PS_MODE_DEV_ auf true setzen. Laden Sie die Seite neu und lesen Sie die Fehlermeldung.

Schritt 2: Loeschen Sie den Inhalt von /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/ und /cache/smarty/cache/. Loeschen Sie class_index.php. Laden Sie die Seite neu.

Schritt 3: Wenn der Fehler auf ein bestimmtes Modul verweist, deaktivieren Sie dieses Modul durch Umbenennung seines Verzeichnisses oder durch Setzen von active = 0 in der Datenbanktabelle ps_module. Laden Sie die Seite neu.

Schritt 4: Wenn der Fehler auf eine Override-Datei verweist, verschieben Sie den Inhalt des Verzeichnisses /override/ an einen temporaeren Backup-Speicherort. Loeschen Sie class_index.php erneut. Laden Sie die Seite neu.

Schritt 5: Ueberpruefen Sie, ob Ihre PHP-Version mit der PrestaShop-Version kompatibel ist, auf die Sie aktualisiert haben. Pruefen Sie phpinfo() oder php -v. Wechseln Sie bei Bedarf die PHP-Version.

Schritt 6: Pruefen Sie die Dateiberechtigungen. Der Update-Prozess kann Dateien mit falscher Eigentuemerzuordnung erstellt haben. Alle PrestaShop-Dateien sollten vom Webserver-Benutzer lesbar sein, und die Verzeichnisse /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/ und /modules/ sollten beschreibbar sein.

Schritt 7: Wenn keiner der obigen Schritte das Problem loest und Sie ein Datenbank-Backup haben, stellen Sie Datenbank und Dateien aus dem Backup wieder her und versuchen Sie das Update erneut, nachdem Sie alle waehrend der Diagnose identifizierten Probleme behoben haben.

Sicheres Update-Verfahren fuer zukuenftige Updates

Praevention ist weitaus besser als Wiederherstellung. Befolgen Sie dieses Verfahren fuer jedes PrestaShop Core-Update, um das Risiko von weissen Seiten und Datenverlust zu minimieren.

Vor dem Update: Erstellen Sie ein vollstaendiges Backup sowohl der Datenbank als auch aller Dateien. Nicht nur die Datenbank, nicht nur die Dateien, sondern beides. Speichern Sie diese Backups moeglichst an einem Ort ausserhalb Ihres Hosting-Kontos. Testen Sie, ob Sie tatsaechlich aus diesen Backups wiederherstellen koennen, bevor Sie fortfahren.

Deaktivieren Sie alle Drittanbieter-Module. Dies ist der einzelne wirksamste Schritt, den Sie unternehmen koennen, um weisse Seiten zu verhindern. Core-Module (die mit PrestaShop ausgeliefert werden) sind so konzipiert, dass sie mit dem Update kompatibel sind, aber fuer Drittanbieter-Module gibt es keine Garantie. Deaktivieren Sie sie vor dem Update und aktivieren Sie sie danach einzeln wieder, wobei Sie den Shop nach jeder Reaktivierung testen.

Deaktivieren Sie das Override-System. Wenn Sie benutzerdefinierte Overrides haben, deaktivieren Sie sie vor dem Update. Bewerten Sie jedes Override nach dem Update neu, um festzustellen, ob es noch kompatibel und noch notwendig ist.

Lesen Sie die Release Notes. Jedes PrestaShop-Release enthaelt Hinweise zu Kompatibilitaetsanforderungen, bekannten Problemen und Breaking Changes. Lesen Sie sie vor dem Update, nicht erst nachdem etwas kaputt ist.

Versetzen Sie den Shop in den Wartungsmodus. Dies verhindert, dass Kunden waehrend des Updates Bestellungen aufgeben und auf Fehler stossen. Navigieren Sie im Back Office zu Shopparameter, Allgemein, Wartung und aktivieren Sie den Wartungsmodus.

Waehrend des Updates: Ueberwachen Sie den Update-Prozess. Schliessen Sie nicht den Browser-Tab und navigieren Sie nicht weg. Wenn das Update laenger als erwartet dauert, pruefen Sie Ihre Server-Fehlerprotokolle auf Timeout- oder Speicherfehler. Wenn der Prozess haengenzubleiben scheint, warten Sie mindestens 10 Minuten, bevor Sie Massnahmen ergreifen, da grosse Shops moeglicherweise umfangreiche Datenbankmigrationen verarbeiten muessen.

Nach dem Update: Leeren Sie alle Caches. Ueberpruefen Sie, ob das Back Office korrekt laedt. Pruefen Sie das Front Office. Aktivieren Sie Module einzeln wieder und pruefen Sie den Shop nach jedem Modul. Aktivieren Sie Overrides einzeln wieder, falls zutreffend. Deaktivieren Sie den Wartungsmodus. Ueberwachen Sie die Fehlerprotokolle fuer die naechsten 24 Stunden.

Rollback-Strategien

Wenn eine Wiederherstellung nicht moeglich oder zu zeitaufwaendig ist, kann ein Rollback auf die vorherige Version die beste Option sein. PrestaShop verfuegt jedoch ueber keinen integrierten Rollback-Mechanismus, sodass Sie diese Moeglichkeit vor Beginn des Updates einplanen muessen.

Vollstaendiger Rollback aus Backup: Stellen Sie sowohl die Datenbank als auch die Dateien aus Ihrem Backup von vor dem Update wieder her. Dies ist der sauberste Ansatz, erfordert aber, dass Sie vor dem Update ein vollstaendiges Backup erstellt haben. Ueberpruefen Sie nach der Wiederherstellung, ob der Shop korrekt funktioniert und keine Bestellungen oder Kundendaten verloren gegangen sind, die waehrend des fehlgeschlagenen Update-Zeitraums erstellt wurden (wenn der Shop im Wartungsmodus war, sollte sich nichts geaendert haben).

Teilweiser Datei-Rollback: Wenn nur die Dateien beschaedigt sind, die Datenbank aber in Ordnung ist, koennen Sie die PrestaShop-Dateien durch die vorherige Version ersetzen und dabei die aktuelle Datenbank beibehalten. Laden Sie die exakte vorherige PrestaShop-Version aus dem offiziellen Release-Archiv herunter, entpacken Sie sie und ueberschreiben Sie die Dateien auf Ihrem Server. Behalten Sie Ihre benutzerdefinierten Module, Themes und Konfigurationsdateien bei. Dieser Ansatz ist riskant, da die Datenbank moeglicherweise teilweise migriert wurde, was eine Inkonsistenz zwischen den Dateien und dem Datenbankschema erzeugt.

Vorwaerts-Fix: Manchmal ist der schnellste Weg nicht der Rollback, sondern die Behebung des spezifischen Fehlers. Wenn der Fehler durch ein einzelnes inkompatibles Modul oder Override verursacht wird, kann das Beheben oder Entfernen dieser einen Komponente Minuten dauern, verglichen mit Stunden fuer einen vollstaendigen Rollback. Dieser Ansatz ist am besten, wenn Sie die Ursache aus der Fehlermeldung klar identifiziert haben.

Die Bedeutung von Datenbank-Backups

Jeder Abschnitt dieses Leitfadens erwaehnt Backups, und das aus gutem Grund. Eine PrestaShop-Datenbank enthaelt jedes Produkt, jede Bestellung, jedes Kundenkonto, jede Konfigurationseinstellung und jeden Inhalt in Ihrem Shop. Sie zu verlieren bedeutet, Ihre Geschaeftsdaten zu verlieren.

Automatische taegliche Backups sind fuer einen produktiven PrestaShop-Shop nicht optional. Konfigurieren Sie das Backup-System Ihres Hosting-Anbieters, verwenden Sie ein Datenbank-Backup-Modul oder richten Sie einen Cronjob ein, der mysqldump in regelmaessigen Abstaenden ausfuehrt. Speichern Sie Backups an mehreren Standorten. Testen Sie Ihr Wiederherstellungsverfahren regelmaessig, um sicherzustellen, dass Backups tatsaechlich verwendbar sind.

Erstellen Sie vor jedem Update ein manuelles Backup zusaetzlich zu Ihren automatischen Backups. Benennen Sie es eindeutig mit dem Datum und der PrestaShop-Version, damit Sie es bei Bedarf sofort identifizieren koennen.

Wann professionelle Hilfe gesucht werden sollte

Wenn Sie alle Schritte in diesem Leitfaden befolgt haben und weiterhin eine weisse Seite sehen, oder wenn die Fehlermeldungen auf tiefgreifende Core-Probleme hinweisen, die Korrekturen auf Code-Ebene erfordern, ist es moeglicherweise an der Zeit, einen PrestaShop-Entwickler hinzuzuziehen. Stellen Sie ihm die gesammelten Fehlermeldungen, die beteiligten PrestaShop-Versionen (vor und nach dem Update), Ihre PHP-Version und alle bereits unternommenen Massnahmen zur Verfuegung. Diese Informationen werden die fuer Diagnose und Loesung benoetigte Zeit erheblich verkuerzen.

Der Versuch, Core-PrestaShop-Dateien manuell zu bearbeiten, ohne die Framework-Architektur zu verstehen, kann zusaetzliche Probleme schaffen. Wenn die Fehlermeldung auf Symfony-Container, Dependency Injection oder Kernel-Konfiguration verweist, sind dies Bereiche, in denen falsche Aenderungen zu mehrfachen Folgefehlern fuehren koennen.