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

Der Shop ist kaputt. Was Sie in den nächsten zehn Minuten tun sollten.

Nach zehn Jahren und 140+ Modulen im Produktiveinsatz haben wir die meisten Arten gesehen, auf die ein PrestaShop-Store umfallen kann, weiße Seiten, 500er, Anmeldeschleifen im Admin, „Speichern"-Buttons, die klammheimlich nichts tun, Bestellabschlüsse, die bei Schritt 3 hängen bleiben. Diese Seite ist das Drehbuch, das wir in unserem eigenen Support-Postfach abarbeiten, bevor wir eine einzige Zeile Code anfassen.

Der mit Abstand größte Fehler, den wir sehen, ist der Panik-Reflex: Jemand bemerkt, dass der Shop nicht erreichbar ist, ändert fünf Dinge gleichzeitig, und nun weiß niemand mehr, was das Problem behoben oder was es noch verschlimmert hat. Tun Sie das nicht. Die Methode, die funktioniert, ist langweilig: Fehler lesen, Logs lesen, eine Sache ändern, prüfen, wiederholen.

Bevor Sie irgendetwas an einem Live-Shop ändern, ziehen Sie einen Datenbank-Dump und ein Datei-Archiv. Wenn Ihr Fix die Lage verschlechtert, brauchen Sie einen Weg zurück, und „Ich merke mir schon, was ich geändert habe" übersteht keinen echten Ausfall.

1. Den Debug-Modus einschalten, ohne sich selbst ins Bein zu schießen

Die Logs-Seite im Back Office von PrestaShop 8.

Jeder Fehler, den PrestaShop abfängt, landet hier mit Schweregrad, Zeitstempel und Objektkontext. Prüfen Sie dies, bevor Sie die Server-Logs prüfen.

Standardmäßig verbirgt PrestaShop Fehler, gut für Kunden, nutzlos für uns. Der Debug-Modus ist der erste Schalter, den wir bei jedem Diagnose-Anruf umlegen.

PrestaShop 1.6 und 1.7

Bearbeiten Sie config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // false in true ändern

Das aktiviert die Fehleranzeige, deaktiviert den Smarty-Cache und setzt error_reporting auf E_ALL hoch. Ab 1.7.7 erhalten Sie zusätzlich die Symfony-Debug-Toolbar am unteren Rand jeder Seite. Allein diese Toolbar hat uns Stunden gespart.

PrestaShop 8.x und 9.x

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

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

Wenn PrestaShop nicht einmal startet

Wenn der Fehler auslöst, bevor PrestaShop seine eigene Konfiguration lädt, erhalten Sie auch mit eingeschaltetem Debug-Modus eine leere Seite und keine Änderung. Zwingen Sie PHP, direkt mit Ihnen zu sprechen, ganz oben in index.php:

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

Das umgeht PrestaShop vollständig und schiebt den rohen PHP-Fatal-Fehler in den Browser. Entfernen Sie es in der Sekunde, in der Sie Ihre Antwort haben.

Lassen Sie den Debug-Modus niemals im Produktivbetrieb an. Er legt Dateipfade, Datenbank-Zugangsdaten, geheime Tokens und Ihren Stack für jeden offen, der einen Fehler auslöst. Wir haben Shops geprüft, bei denen das monatelang aktiv war. Jeder einzelne war ein Sicherheitsvorfall, der nur darauf wartete, dokumentiert zu werden.

2. Der White Screen of Death

Eine komplett leere Seite bedeutet, dass PHP auf einen Fatal-Fehler gestoßen ist, aber display_errors ausgeschaltet ist. Der Fehler existiert. Er wurde irgendwo festgehalten. Sie müssen nur herausfinden, wo.

Schritt 1: das Log lesen

Der Fatal-Fehler steht in einem dieser Logs:

• var/logs/prod.log (PS 1.7)
• var/log/prod.log (PS 8+ und 9)
• Apache- oder Nginx-Fehlerlog (Fehler auf Serverebene)
• PHP-Fehlerlog (der Pfad steht in php.ini; bei Shared Hosting ist es meist ~/logs/error.log)

Wenn Sie das Log nicht zuerst lesen, raten Sie nur. Das Log nennt Datei, Zeilennummer und Meldung. Das ist die Antwort.

Schritt 2: den Debug-Modus aktivieren

Wenn Sie nicht auf die Logs zugreifen können (Shared Hosting ohne SSH, Panik im Moment), legen Sie _PS_MODE_DEV_ um und laden Sie neu. Jetzt wird der Fehler im Browser dargestellt.

Schritt 3: der Plausibilitätstest über die CLI

Wenn selbst die Debug-Seite leer ist, ist der Boot-Vorgang selbst defekt. Testen Sie von der Kommandozeile aus:

php -l config/defines.inc.php           # Syntaxprüfung
php -r "require 'config/config.inc.php';"  # vollständiger Ladetest

Die fünf Ursachen, die wir im Support sehen

• Speicher erschöpft. Setzen Sie memory_limit = 512M in php.ini. 256M ist die Untergrenze für PS 1.7+, 512M für PS 8+, alles darunter und ein einziger Massenimport sprengt es.
• PHP-Versionskonflikt. PS 1.6 stirbt unter PHP 7.4+. PS 1.7.0–1.7.6 stirbt unter PHP 8.0+. PS 9.x benötigt PHP 8.1+. Wir haben mit angesehen, wie ein routinemäßiges PHP-Upgrade des Servers fünf Shops auf einmal lahmlegte, weil niemand die Matrix geprüft hatte.
• Modul-Fatal-Fehler. Das zuletzt installierte Modul ist Verdächtiger Nr. 1. Benennen Sie seinen Ordner per FTP um: modules/problem_module → modules/problem_module_disabled. PrestaShop überspringt es und der Shop lädt.
• Beschädigter Cache. Leeren Sie var/cache/ (PS 1.7+) oder cache/smarty/compile/ (PS 1.6). Wenn ein Deploy eine Cache-Datei halb schreibt, liest die nächste Anfrage Müll und stirbt.
• Defektes Override. Benennen Sie das gesamte Verzeichnis override/ um. Wenn der Shop zurückkommt, haben Sie es gefunden. Grenzen Sie dann ein, indem Sie die Dateien eine nach der anderen wieder einführen.

3. 500 Internal Server Error

Ein 500er ist der Server, der Ihnen mitteilt, dass etwas schiefgelaufen ist, bevor PHP die Chance hatte, mit Ihnen zu sprechen. Der Fehler steht oft nicht einmal in den PrestaShop-Logs, prüfen Sie zuerst das Apache- oder Nginx-Fehlerlog.

Die .htaccess-Falle

Die häufigste Ursache, die wir sehen. Testen Sie sie sofort:

mv .htaccess .htaccess.bak

Wenn der Shop lädt (mit defekten URLs und hässlichen Query-Strings), war .htaccess das Problem.

• mod_rewrite nicht aktiviert. a2enmod rewrite && systemctl restart apache2. Erforderlich für sprechende URLs.
• AllowOverride None. Der Virtual Host muss die Regeln von PrestaShop zulassen. Stellen Sie auf AllowOverride All um.
• Direktiven, die der Hoster blockiert. Manche Shared Hosts verbieten Options oder php_value. Kommentieren Sie Blöcke aus, bis der 500er verschwindet.
• Neu generieren. Shop-Einstellungen → Traffic & SEO → „.htaccess-Datei generieren" baut sie aus PrestaShops eigener Vorlage neu auf.

Dateiberechtigungen

Verzeichnisse 755, Dateien 644, beschreibbare Verzeichnisse (var/cache, img, upload) 775. Wer Ihnen sagt, Sie sollen chmod 777 machen, liegt falsch und reißt mit ziemlicher Sicherheit auch noch anderswo ein Sicherheitsloch auf.

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

PHP-Limits, die man einmal setzt und dann vergisst

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

max_input_vars ist der stille Killer, PrestaShop-Produktseiten mit Kombinationen überschreiten den Standardwert von 1000 mühelos, und PHP verwirft den Rest Ihres POST einfach ohne Fehlermeldung. Sie speichern ein Produkt, die Hälfte der Felder springt zurück, und nichts wird protokolliert.

4. Modulkonflikte

Module verursachen mehr Shop-Ausfälle als jede andere einzelne Kategorie, mit großem Abstand. Das Muster ist fast immer: Ein neues Modul installieren, etwas anderes bricht. Zwei Module versuchen, sich an derselben Stelle einzuhaken oder dieselbe Klasse zu überschreiben, und das zweite, das installiert wird, verliert.

Die Isolationsmethode

1. Deaktivieren Sie jedes Drittanbietermodul im Modul-Manager.
2. Bestätigen Sie, dass das Problem verschwunden ist.
3. Aktivieren Sie sie in Gruppen wieder, dann einzeln, und testen Sie nach jedem.

Wenn der Admin selbst defekt ist, deaktivieren Sie über die Datenbank:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Oder den Ordner über SSH/FTP umbenennen:
mv modules/problem_module modules/problem_module.bak

Override-Konflikte

Zwei Module können nicht dieselbe Klassenmethode überschreiben. Die zweite Installation schlägt rundheraus fehl mit „method X is already overridden by module Y". Suchen Sie in override/classes/ und override/controllers/ nach der Kollision. Wenn Sie eine Override-Datei manuell entfernen, löschen Sie var/cache/*/class_index.php, sonst verwendet PrestaShop weiterhin die gecachte Version der Override-Map und Sie denken, es habe sich nichts geändert.

Hook-Reihenfolge

Wenn zwei Module sich auf demselben Hook registrieren, bestimmt die Position, wer zuerst gerendert wird. Sortieren Sie unter Design → Positionen neu, oder fragen Sie ps_hook_module direkt ab, um die aktuelle Reihenfolge zu sehen.

Wenn Sie ein Ticket bei einem Modul-Entwickler eröffnen, geben Sie mit an: den genauen Log-Eintrag, die PrestaShop-Version, die PHP-Version, die anderen aktiven Module und die Schritte zur Reproduktion. „Der Shop ist kaputtgegangen" ist ein 48-Stunden-Ticket; „hookActionCartSave aus Modul X bricht mit diesem Stacktrace auf PS 8.1.4 + PHP 8.2 ab" ist ein 2-Stunden-Ticket.

Wenn Sie bei einem kommerziellen Modul feststecken, eröffnen Sie eine Support-Anfrage mit diesen Informationen parat. Ein präziser Hook-, Override- oder Request-Fehler lässt sich schneller diagnostizieren als ein vages „Seite kaputt".

5. Cache-Probleme

„Ich habe den Cache geleert, und es hat nichts gebracht" bedeutet fast immer, dass der falsche Cache geleert wurde. PrestaShop betreibt mindestens fünf Caches parallel, und sie wissen nichts voneinander.

Die fünf Schichten

• Smarty. Kompilierte .tpl-Dateien in var/cache/prod/smarty/. Das ist es, was geleert wird, wenn Sie im Admin auf „Cache leeren" klicken.
• Symfony. Kompilierter Service-Container, Routen, Übersetzungen in var/cache/prod/. PS 8+ stützt sich stark darauf, Konfigurationsänderungen, die „nicht griffen", bedeuten meist einen veralteten Symfony-Cache.
• OPcache. PHP-Bytecode im Shared Memory. Im Dateisystem unsichtbar, durch das Löschen von Dateien nicht berührt, und die Quelle der Hälfte der „Ich habe den Fix hochgeladen, aber der Bug ist immer noch da"-Tickets.
• Objekt-Cache. Der Datenbank-Abfrage-Cache von PrestaShop (datei-basiert oder Redis).
• Browser und CDN. CSS, JS, Bilder, die auf dem Gerät des Besuchers und bei Cloudflare oder Ihrem CDN der Wahl gecacht werden.

Alles leeren

Über den Admin: Erweiterte Einstellungen → Leistung → Cache leeren. Wenn der Admin selbst nicht erreichbar ist:

# Das Cache-Verzeichnis direkt leeren
rm -rf var/cache/prod/* var/cache/dev/*

# Oder die Symfony-Konsole auf PS 8+/9 nutzen
php bin/console cache:clear --env=prod

OPcache

Nach dem Bearbeiten von PHP-Dateien kann OPcache weiterhin den alten Bytecode ausliefern. Das CLI-opcache_reset() leert nur den CLI-Pool, nicht den Web-Pool. Die beiden sind getrennt. Der zuverlässige Trick: Legen Sie eine einzeilige PHP-Datei wie opcache.php mit <?php opcache_reset(); ab, rufen Sie sie im Browser auf, löschen Sie sie.

Wenn der Cache „festhängt"

Passen Sie die Cache-Schicht an die Art der Änderung an:

• Template-Änderungen → Smarty
• PHP-Code-Änderungen → OPcache (Web-Reset)
• Konfigurationsänderungen (services.yml, Hooks) → Symfony
• CSS/JS → Browser (Ctrl+Shift+R) und CDN
• „Class not found" → class_index.php löschen

Nach jedem Deploy: Symfony-Cache, Smarty-Cache, OPcache (über das Web, nicht CLI), CDN. Verpassen Sie auch nur einen, und der Deploy sieht so aus, als hätte er „nicht funktioniert". Das ist die mit Abstand häufigste Ursache der „Wir haben deployt, aber der Fix ist nicht live"-Meldungen, die uns erreichen.

6. Datenbank-Ärger

Datenbankprobleme treten meist nach einem fehlgeschlagenen PrestaShop-Upgrade, einem unterbrochenen Import oder einem abgelaufenen Skript auf, das eine halbe Transaktion hinterlassen hat. Wenn das Problem eher Aufgeblähtheit als Beschädigung ist, beginnen Sie mit Database Cleanup oder dem entsprechenden SQL-Audit, bevor Sie dem Server die Schuld geben.

Beschädigte Tabellen

# Alles prüfen
mysqlcheck -u root -p prestashop_db --check

# Reparieren (nur MyISAM)
REPAIR TABLE ps_product;

# Für InnoDB (das jede moderne Installation verwendet) an Ort und Stelle neu aufbauen:
ALTER TABLE ps_product ENGINE=InnoDB;

Fehlende Spalten nach einem fehlgeschlagenen Upgrade

Der klassische Fehler nach dem Upgrade: Unknown column 'new_column' in 'field list'. Das Upgrade-Skript brach auf halbem Weg ab und hinterließ einige Tabellen halb migriert.

# Was tatsächlich da ist
SHOW CREATE TABLE ps_product\G

# Sehen Sie in install-dev/upgrade/sql/ oder install/upgrade/sql/ nach den Upgrade-Skripten
# Fügen Sie die fehlende Spalte von dort aus manuell hinzu:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Strukturen vergleichen

Wenn Sie nicht wissen, was fehlt, installieren Sie ein frisches PrestaShop derselben Version daneben, machen Sie mysqldump --no-data von beiden Datenbanken und vergleichen Sie. Jede fehlende Tabelle, Spalte und jeder fehlende Index fällt in zwei Sekunden aus dem Diff heraus.

Festsitzende Abfragen

SHOW FULL PROCESSLIST, um sie zu finden, KILL <id>, um zu beenden, SHOW ENGINE INNODB STATUS, wenn Sie ein Lock-Wait vermuten. Wir haben mit angesehen, wie eine einzige festsitzende Cron-Abfrage auf ps_cart den Bestellabschluss eines ganzen Shops vierzig Minuten lang blockierte, beenden Sie sie und der Shop löst sich sofort.

Führen Sie ALTER TABLE nicht während der Geschäftszeiten auf Tabellen mit mehreren Millionen Zeilen aus. Wir haben gesehen, wie absolut vernünftige Schemaänderungen ps_product auf einem stark frequentierten Shop zehn Minuten lang sperrten. Jeder Bestellabschluss hängt, bis sie fertig ist.

7. Theme-Probleme

Fehlende Templates

Fehler: unable to load template file 'module:modulename/...'. PrestaShop schaut zuerst im Theme-Override (themes/your_theme/modules/...) und greift erst dann auf das modul-eigene Template zurück, wenn das Theme-Override nicht existiert. Wenn ein Theme-Override auf eine Datei zeigt, die das Modul umbenannt oder gelöscht hat, erhalten Sie dies. Und denken Sie daran: Dateinamen sind unter Linux case-sensitiv. Header.tpl Und header.tpl sind unterschiedliche Dateien.

Smarty-Kompilierungsfehler

Die drei Dinge, die wir am häufigsten sehen:

• Nicht zusammenpassende Tags. Jedes {if} braucht ein {/if}, jedes {foreach} braucht ein {/foreach}.
• JavaScript-Klammern. Umschließen Sie JS mit {literal}...{/literal}, sonst versucht Smarty, Ihre Objekt-Literale zu parsen.
• Kodierung. TPL-Dateien müssen UTF-8 ohne BOM sein. Ein BOM am Anfang reicht aus, um das gesamte Template zu zerstören.

Assets, die nicht laden

Öffnen Sie die DevTools, den Netzwerk-Tab, suchen Sie nach den 404ern. Übliche Verdächtige: falsche Pfade in theme.yml, ein CCC-Cache, der nach einem Deploy nicht neu aufgebaut wurde, oder ein CDN, das auf einen Pfad zeigt, der nicht mehr existiert.

Child-Theme-Probleme

Eltern-Theme gelöscht (Child scheitert mit „Invalid theme"), veraltete Template-Overrides, nachdem ein Eltern-Update die zugrunde liegenden Templates geändert hat, oder ein fehlender Eintrag in der theme.yml des Child, durch den Module aus den Hooks verschwinden. Unsere eigenen Shops laufen auf einem Child von Hummingbird, und genau dieses letzte Problem beißt bei jedem PS-Upgrade.

Lesen Sie vor jedem PrestaShop-Upgrade das Changelog auf Template-Änderungen. Jedes Child-Theme-Override eines geänderten Templates muss überprüft werden, manchmal ein Einzeiler-Merge, manchmal eine komplette Neufassung.

8. PHP-Versionskompatibilität

Eine überraschende Menge der „Der Shop ist nach dem Hosting-Upgrade kaputtgegangen"-Tickets ist schlicht PHP-Versionsdrift. Die Matrix:

* PS 1.7.8 hat partielle PHP-8.0-Unterstützung. Der Kern läuft größtenteils, die meisten Drittanbietermodule nicht.

Die Fehler, die jeder Upgrade-Schritt wirft

• PHP 7.x → 8.0. TypeError: expects string, null given an allen Ecken und Enden. PHP 8 hat aufgehört, null in strlen(), strpos() und Konsorten still zu casten.
• PHP 8.0 → 8.1. Return type should be compatible durch strengere Vererbungsregeln. FILTER_SANITIZE_STRING ist veraltet und wird entfernt, die meisten Module nutzen es noch.
• PHP 8.1 → 8.2. Dynamische Eigenschaften sind veraltet. Jedes Modul, das $this->someThing = ... auf einer Klasse setzt, die die Eigenschaft nicht deklariert hat, protokolliert eine Warnung.

Zwei Dinge sollten Sie zum Hosting wissen: CLI- und Web-PHP-Versionen können auf Multi-PHP-Servern unterschiedlich sein, prüfen Sie daher immer mit phpinfo() im Browser, nicht nur mit php -v auf der Kommandozeile. Und testen Sie vor jedem Produktiv-Upgrade auf einer Staging-Umgebung, führen Sie php -l über jede Moduldatei aus und aktualisieren Sie zuerst die Module.

9. E-Mails werden nicht versendet

• Vom Admin aus testen. Erweiterte Einstellungen → E-Mail → „Test-E-Mail senden". Das Ergebnis sagt Ihnen, ob PrestaShop überhaupt mit seinem Mail-Backend sprechen kann.
• SMTP-Einstellungen prüfen. Host, Port (587 für TLS, 465 für SSL), Benutzername, Passwort.
• ps_mail inspizieren. Wenn Zeilen in dieser Tabelle landen, hat PrestaShop die Nachricht versendet. Ihr Problem ist die Zustellung, nicht die Erzeugung.
• PHP-mail() ist unzuverlässig. Wechseln Sie bei jedem Produktiv-Shop zu SMTP. Es ist überall zuverlässiger und liefert Ihnen echte Zustellungsdiagnosen.
• SPF, DKIM, DMARC. Moderne Zustellung erfordert alle drei. Ohne sie werfen Gmail und Outlook Ihre Transaktions-E-Mails still in den Müll.
• Bestellbestätigungen im Speziellen. Wenn die Bestellung existiert, die E-Mail aber fehlt, gibt Resend Order Confirmation dem Support-Personal einen kontrollierten Weg zum erneuten Versand, nachdem SMTP behoben ist.

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

10. Der Shop ist plötzlich langsam geworden

Schnelldiagnose

Prüfen Sie den Plattenplatz (df -h), die Load-Average (uptime), MySQL (SHOW FULL PROCESSLIST) und den OPcache-Status. Eine volle Platte legt alles still und leise lahm. MySQL kann nicht schreiben, Logs können nicht rotieren, Caches können sich nicht füllen.

Die Ursachen, die wir am häufigsten sehen

• Debug-Modus eingeschaltet gelassen. Prüfen Sie zuerst _PS_MODE_DEV_. Diese eine Zeile löst mehr „Der Store ist langsam geworden"-Tickets als alles andere auf dieser Liste.
• Volle Platte. Schon 95 % voll reicht aus. MySQL braucht Spielraum, um temporäre Tabellen zu schreiben.
• Eine schlechte Modul-Abfrage. Eine nicht indizierte Abfrage auf einer großen Tabelle hängt jeder Seite Sekunden an. Der Symfony-Profiler (PS 8+) zeigt Ihnen die Abfragezeiten pro Seite.
• Cron-Jobs, die sich stapeln. Zwei Importskripte, die zur gleichen Zeit gestartet sind, und keines war fertig, bevor der nächste Cron-Tick kam. Lock-Dateien, oder verwenden Sie eine Queue.
• Aufgeblähte Tabellen. ps_connections, ps_log, ps_cart, ps_guest wachsen ewig weiter, sofern Sie sie nicht beschneiden. Wir haben ps_connections mit 40M Zeilen auf Shops gesehen, die sie nie gekürzt haben.

Vollständiger Leitfaden: PrestaShop-Performance-Optimierung.

Wenn die Verlangsamungen immer wiederkehren, nachdem die Grundlagen geprüft sind, ist Performance Revolution das Modul, das wir genau dafür gebaut haben, es profiliert teure Seiten, Hooks, Module und Abfragen innerhalb des Shops. Nutzen Sie es nach den Logs und dem Server-Gesundheitscheck, nicht stattdessen.

11. Häufige Fehlermeldungen, entschlüsselt

„Class 'SomeClass' not found"

Löschen Sie var/cache/prod/class_index.php (es wird bei der nächsten Anfrage neu erzeugt), führen Sie composer dump-autoload auf PS 1.7+ aus und prüfen Sie die Groß-/Kleinschreibung des Dateinamens unter Linux. Wenn ein Modul nur teilweise gelöscht wurde, müssen Sie auch Zeilen in ps_hook_module und ps_module aufräumen.

„CSRF token error" / „Invalid token"

Session abgelaufen (erhöhen Sie session.gc_maxlifetime), mehrere Admin-Tabs, die sich um dieselbe Session streiten (aktualisieren), ein Reverse Proxy, der Cookies entfernt (Admin vom Caching ausschließen), oder (peinlicherweise) die Server-Uhr ist abgedriftet.

„Ajax error"

Öffnen Sie die DevTools, den Netzwerk-Tab, reproduzieren Sie die Aktion. Die fehlgeschlagene Anfrage (rot, Status 500) ist dort. Der Antwort-Tab enthält den eigentlichen PHP-Fehler. „Ajax error" selbst sagt Ihnen nichts; die zugrunde liegende Antwort immer.

„Allowed memory size exhausted"

Erhöhen Sie memory_limit = 512M. Wenn der Shop weiterhin mehr frisst, handelt es sich um ein Speicherleck in einem Modul, und der Symfony-Profiler sagt Ihnen, welches.

„Duplicate entry for key"

Eine Verletzung einer Unique-Constraint. Häufig bei Produktimporten (doppelte Referenzen), Multistore-Modulinstallationen, die denselben Authorization-Role-Slug treffen, oder einem erneuten Lauf eines Upgrades, das beim letzten Mal nur halb durchlief.

„Deprecated: ...", die die Logs flutet

Eine Warnung, kein Fehler. Sie können sie mit error_reporting = E_ALL & ~E_DEPRECATED unterdrücken, aber das ist ein Pflaster. Diese Warnungen sind Fatal-Fehler in der nächsten PHP-Version. Aktualisieren Sie stattdessen das Modul.

12. Notfall-Wiederherstellung

Admin-Passwort zurücksetzen

Die einzige Methode, die über alle PS-Versionen hinweg funktioniert: ein kurzes PHP-Skript, das die hauseigene Hashing-Klasse von PrestaShop verwendet. Hochladen, ausführen, sofort löschen.

<?php
require __DIR__ . '/config/config.inc.php';
$crypto = new \PrestaShop\PrestaShop\Core\Crypto\Hashing();
$hash = $crypto->hash('YourNewPassword!');
Db::getInstance()->execute(
    "UPDATE ps_employee SET passwd = '" . pSQL($hash) . "' WHERE email = 'admin@yourdomain.com'"
);
echo "Password updated. DELETE THIS FILE NOW.\n";

Auf PS 1.6 (das MD5 + Cookie-Key verwendete) nutzen Sie denselben Ansatz, Tools::encrypt('YourNewPassword!') erzeugt den korrekten Hash für diese Version.

Löschen Sie das Reset-Skript in der Sekunde, in der Sie angemeldet sind. Wer es findet, kann jedes Admin-Passwort Ihres Shops zurücksetzen. Wir haben gesehen, wie diese jahrelang auf Live-Shops zurückblieben.

Ein defektes Modul deaktivieren

-- Über die Datenbank
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Über das Dateisystem (zuverlässiger, stoppt auch das Ausführen des Install-Hooks)
mv modules/broken_module modules/broken_module.disabled

Um jedes Drittanbietermodul auf einmal abzuschalten, setzen Sie UPDATE ps_module SET active = 0 für jeden Namen, der nicht in der nativen PS-Liste steht (ps_banner, ps_categorytree, ps_facetedsearch usw.).

Overrides deaktivieren

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

Ein Flag, jedes Override übersprungen. Wenn Sie Overrides vermuten, aber nicht wissen, welches, bringt das den Shop hoch, während Sie ermitteln.

Aus einem Backup wiederherstellen

Versetzen Sie den Shop in den Wartungsmodus, stellen Sie die Datenbank wieder her (mysql -u root -p db < backup.sql), stellen Sie die Dateien wieder her, leeren Sie jeden Cache (rm -rf var/cache/*), setzen Sie OPcache zurück und gehen Sie dann den Shop von oben bis unten durch: Startseite, Produktseite, Warenkorb, Bestellabschluss, Admin-Anmeldung. Trauen Sie einer Wiederherstellung erst, wenn Sie eine Testbestellung aufgegeben haben.

Wartungsmodus, wenn der Admin defekt ist

Wartungsmodus in PrestaShop 8.

Der Aktivieren/Deaktivieren-Schalter, die IP-Whitelist für Testzugriff und die individuelle Wartungsnachricht. Wenn Sie den Shop für Reparaturen offline nehmen müssen, ist hier der Ort.

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. Arbeiten Sie von oben nach unten. Überspringen Sie keine Schritte, weil sie „offensichtlich erscheinen".

Phase 1: Informationen sammeln

• Was hat sich geändert? Modul-Installation oder -Update, PS-Update, PHP-Update, Server-Änderung, Theme-Anpassung?
• Wann genau hat es angefangen? Gleichen Sie es mit Deploy-Logs und Cron-Zeitstempeln ab.
• Wer ist betroffen? Alle, bestimmte Browser, nur Admin, nur Front Office, nur angemeldete Kunden?
• Was ist der genaue Fehler? Debug-Modus an, Browser-Konsole offen, alle Logs geprüft.

Phase 2: isolieren

• Server: Platte (df -h), Speicher (free -m), CPU (top), MySQL (SHOW PROCESSLIST).
• PHP: Version (php -v), Syntax (php -l), Live-Konfiguration (phpinfo()).
• Cache: jede Schicht leeren, Smarty, Symfony, OPcache, Browser. Im Inkognito-Modus testen.
• Module: das neueste zuerst deaktivieren. Falls unklar, alle Drittanbieter deaktivieren und einzeln wieder aktivieren.
• Theme: vorübergehend auf ein Standard-Theme umstellen.
• Datenbank: mysqlcheck, MySQL-Fehlerlog, Struktur-Diff, wenn Sie ein schlechtes Upgrade vermuten.
• Berechtigungen: ls -la auf var/cache, var/logs, img, upload.

Phase 3: beheben und prüfen

• EINE Änderung nach der anderen. Testen. Wenn sie es nicht behoben hat, vor dem nächsten Versuch zurücknehmen.
• Nach jedem Fix alle Caches leeren.
• Den Shop durchgehen: Startseite, Kategorie, Produkt, Warenkorb, Bestellabschluss, Admin.
• Im Inkognito-Modus und einem anderen Browser testen.
• Den Debug-Modus ausschalten. Alle temporären Skripte löschen.

Phase 4: Wiederholung verhindern

• Notieren Sie, was passiert ist und was es behoben hat. Ihr zukünftiges Ich wird Ihrem heutigen Ich danken.
• Richten Sie Monitoring ein: Verfügbarkeit, Fehlerlogs, Plattenplatz.
• Überprüfen Sie, ob Backups funktionieren, indem Sie tatsächlich eines in einer Staging-Umgebung wiederherstellen.

Schnellreferenz

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

Schlüsseldateien

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

Wesentliche CLI-Befehle (PS 1.7+)

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

Jede Fehlersuche beginnt auf dieselbe Weise: Fehler lesen, Logs lesen, Ursache isolieren. Erfahrene Entwickler merken sich nicht jeden Fehler auswendig. Wir wissen, wo wir nachsehen müssen. Diese Seite ist genau diese Landkarte.

Weiterführende Lektüre

• PrestaShop-Hooks-Leitfaden: Display, Action & Overrides: wenn das Problem eine Hook-Reihenfolge oder ein Override-Konflikt ist
• PrestaShop-Child-Themes: Anpassungsleitfaden für Classic & Hummingbird: Theme-Overrides sauber beheben
• PrestaShop-Performance-Optimierung: für langsame Seiten, Cache-Ärger und Engpässe
• PrestaShop-E-Mail-Zustellbarkeit: SMTP, SPF, DKIM, DMARC, Zustellungsfehler
• PrestaShop-Hosting-Leitfaden: PHP-Limits, Server-Konfiguration, Hosting-Anforderungen
• Performance Revolution: das Profiler-Modul, zu dem wir greifen, wenn Verlangsamungen immer wiederkehren

Passende Fragen

• Wie aktiviere ich den Debug-Modus in PrestaShop?
• Meine Modulkonfiguration wird nicht gespeichert.
• PrestaShop-Cache verursacht Probleme. Soll ich ihn deaktivieren?
• Ich habe versehentlich meine .htaccess-Datei kaputt gemacht. Wie repariere ich sie?
• Das Modul zeigt den Fehler „Class not found“ oder „Namespace not found“.
• PrestaShop Warenkorb aktualisiert sich nicht: Cache-, JS- und Modulkonflikte