Problemy PrestaShop: biały ekran i błędy 500

Podejście do rozwiązywania problemów

Coś się zepsuło. Instynkt podpowiada, żeby zacząć zmieniać różne rzeczy. Oprzyj się temu. Zmienianie wielu rzeczy naraz uniemożliwia ustalenie, co naprawdziło problem. Metoda, która działa: obserwuj, wyizoluj, napraw, zweryfikuj. Przeczytaj błąd. Sprawdź logi. Zmień jedną rzecz. Przetestuj. Powtórz.

Zanim cokolwiek zmienisz, zrób kopię zapasową. Zrzut bazy danych + archiwum plików. Jeśli Twoja poprawka pogorszy sytuację, potrzebujesz drogi powrotnej.

1. Włączanie trybu debugowania

Tryb debugowania to Twoje pierwsze narzędzie przy każdym problemie. PrestaShop domyślnie ukrywa błędy — dobrze dla klientów, fatalnie przy rozwiązywaniu problemów.

PrestaShop 1.6 i 1.7

Edytuj config/defines.inc.php:

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

To włącza wyświetlanie błędów, wyłącza cache Smarty i ustawia error_reporting na E_ALL. W PS 1.7.7+ włącza również pasek debugowania Symfony na dole każdej strony.

PrestaShop 8.x i 9.x

Podejście z defines.inc.php nadal działa, ale PS 8+ odczytuje również plik .env:

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

Awaryjne rozwiązanie zastępcze

Jeśli błąd występuje zanim PrestaShop załaduje swoją konfigurację, wymuś wyświetlanie błędów PHP na początku index.php:

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

W PS 1.7.7+ tryb debugowania włącza również profiler Symfony pokazujący każde zapytanie do bazy danych, zużycie pamięci, trafienia/chybienia cache oraz renderowane szablony.

Nigdy nie zostawiaj trybu debugowania włączonego na produkcji. Ujawnia ścieżki plików, dane bazy danych i wewnętrzną logikę każdemu.

2. Biały ekran śmierci (WSOD)

Pusta biała strona oznacza, że PHP natrafił na błąd krytyczny, ale display_errors jest wyłączone. Błąd istnieje — jest po prostu ukryty.

Krok 1: Sprawdź log błędów

Błąd jest zawsze gdzies zapisany: var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), log błędów Apache lub log błędów PHP. Na hostingu współdzielonym: ~/logs/error.log.

Krok 2: Włącz tryb debugowania

Jeśli logi nie są dostępne, włącz _PS_MODE_DEV_ i odśwież stronę.

Krok 3: Sprawdzenie PHP z linii poleceń

Jeśli strona jest całkowicie pusta, przetestuj za pomocą PHP: php -l config/defines.inc.php (sprawdzenie składni) lub php -r "require 'config/config.inc.php';" (test ładowania).

Najczęstsze przyczyny

• Wyczerpanie limitu pamięci: Zwiększ w php.ini: memory_limit = 512M (minimum 256M dla PS 1.7+, 512M dla PS 8+).
• Niezgodność wersji PHP: PS 1.6 nie działa na PHP 7.4+. PS 1.7.0-1.7.6 nie działa na PHP 8.0+. PS 9.x wymaga PHP 8.1+.
• Błąd krytyczny w module: Zmień nazwę folderu modułu przez FTP: modules/problem_module na modules/problem_module_disabled.
• Uszkodzony cache: Usuń wszystko z var/cache/ (PS 1.7+) lub cache/smarty/compile/ (PS 1.6).
• Uszkodzony override: Tymczasowo zmień nazwę katalogu override/, aby przetestować.

3. Błąd 500 Internal Server Error

HTTP 500 oznacza, że serwer natrafił na warunek, którego nie mógł obsłużyć. W przeciwieństwie do WSOD, to może nawet nie dotrzeć do PHP.

Problemy z .htaccess

Najczęstsza przyczyna. Przetestuj tymczasowo zmieniając nazwę: mv .htaccess .htaccess.bak. Jeśli strona się załaduje (z niepoprawnie działającymi URLami), problem leży w .htaccess.

• mod_rewrite nie włączony: a2enmod rewrite && systemctl restart apache2
• AllowOverride None: Musi być AllowOverride All w konfiguracji virtual hosta.
• Nieobsługiwane dyrektywy: Niektóre hostingi współdzielone blokują Options lub php_value. Komentuj sekcje po kolei, aż znajdziesz winowajcę.
• Regeneracja: Shop Parameters → Traffic & SEO → "Generate .htaccess file".

Uprawnienia plików

Katalogi: 755, pliki: 644, katalogi z prawem zapisu (var/cache, img, upload): 775. Nigdy 777.

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

Limity PHP

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

max_input_vars jest często pomijany — strony produktów PS z kombinacjami przekraczają domyślne 1000.

4. Konflikty modułów

Moduły są najczęstszym źródłem problemów. Dwa moduły próbujące robić to samo będą ze sobą kolidować.

Metoda izolacji

1. Wyłącz wszystkie moduły firm trzecich przez Module Manager.
2. Potwierdź, że problem zniknął.
3. Włączaj moduły ponownie jeden po drugim, testując po każdym.

Jeśli panel administracyjny jest uszkodzony, wyłącz przez bazę danych:

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

Konflikty override

Dwa moduły nie mogą nadpisać tej samej klasy. Sprawdź override/classes/ i override/controllers/. Jeśli ręcznie usuniesz override, usuń var/cache/*/class_index.php, aby wymucić regenerację.

Priorytet hooków

Gdy dwa moduły używają tego samego hooka, kolejność wykonania ma znaczenie. Dostosuj w Design → Positions lub zapytaj tabelę ps_hook_module, aby zobaczyć kolejność wykonania per hook.

Zgłaszając konflikt modułów deweloperowi, dołącz: dokładny błąd z logu, wersję PS, wersję PHP, inne aktywne moduły oraz kroki do odtworzenia problemu.

5. Problemy z cache

PrestaShop posiada wiele niezależnych warstw cache. Gdy "wyczyść cache" nie działa, prawdopodobnie wyczyściłeś niewłaściwy.

Warstwy cache

• Smarty: Skompilowane pliki TPL w var/cache/prod/smarty/.
• Symfony: Skompilowane kontenery, trasy, tłumaczenia w var/cache/prod/.
• OPcache: Bajtkod PHP w pamięci współdzielonej — niewidoczny w systemie plików.
• Cache obiektów: Cache zapytań do bazy danych (plikowy lub Redis).
• Cache przeglądarki: CSS, JS, obrazy na urządzeniu odwiedzającego.

Czyszczenie wszystkiego

Panel administracyjny: Advanced Parameters → Performance → Clear cache. Gdy panel administracyjny nie działa:

# 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

Po edycji plików PHP, OPcache może nadal serwować starą wersję. Zresetuj przez żądanie webowe — stwórz tymczasowy plik z opcache_reset();, odwiedź go w przeglądarce, usuń go. Reset z CLI czyści tylko cache CLI, nie cache webowe.

Gdy cache się "zakleszczy"

Dopasuj cache do zmiany: szablon → Smarty, kod PHP → OPcache, konfiguracja → Symfony, CSS/JS → przeglądarka (Ctrl+Shift+R). Sprawdź też uprawnienia var/cache/, usuń class_index.php, aby wymucić regenerację, i wyczyść cache CDN osobno.

Po każdym wdrożeniu: wyczyść cache Symfony, cache Smarty, OPcache (przez web), cache CDN. Pominięcie któregokolwiek sprawia, że wdrożenie wygląda, jakby "nie zadziałało."

6. Problemy z bazą danych

Problemy z bazą danych zazwyczaj pojawiają się po nieudanych aktualizacjach, przerwanych importach lub operacjach, które przekroczyły limit czasu.

Uszkodzone tabele

# 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;

Brakujące kolumny po nieudanej aktualizacji

Błąd: Unknown column 'new_column' in 'field list'. Aktualizacja została przerwana, pozostawiając niepełne tabele.

# 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';

Porównywanie struktur

Zainstaluj świeżą kopię swojej wersji PS, zrzucić obie struktury za pomocą mysqldump --no-data i porównać je, aby wykryć brakujące tabele, kolumny i indeksy.

Zablokowane zapytania

Uruchom SHOW FULL PROCESSLIST, aby znaleźć zablokowane zapytania, KILL <id>, aby je zakończyć, oraz SHOW ENGINE INNODB STATUS, aby sprawdzić oczekiwania na blokady.

Nigdy nie uruchamiaj ALTER TABLE na dużych tabelach produkcyjnych w godzinach pracy. Dodanie kolumny do tabeli z milionem wierszy może ją zablokować na minuty.

7. Problemy z motywem

Brakujące szablony

Błąd: unable to load template file 'module:modulename/...'. PrestaShop najpierw szuka w nadpisaniu motywu (themes/your_theme/modules/...), potem w domyślnym szablonie modułu. Jeśli nadpisanie motywu odwołuje się do usuniętego lub przemianowanego pliku, pojawia się ten błąd. Na Linuksie nazwy plików rozróżniają wielkość liter.

Błędy kompilacji Smarty

Niedopasowane tagi (każdy {if} wymaga {/if}), nawiasy klamrowe JavaScript (owiń JS w {literal}{/literal}) oraz problemy z kodowaniem (pliki TPL muszą być w UTF-8 bez BOM) to najczęstsi winowajcy.

Błędy ładowania zasobów

Sprawdź konsolę przeglądarki (F12 → Network) pod kątem błędów 404. Typowe przyczyny: złe ścieżki w theme.yml, uszkodzony cache CCC, błędna konfiguracja CDN.

Problemy z motywem potomnym

Usunięty motyw nadrzędny (motyw potomny wyrzuca błąd "Invalid theme"), przestarzałe nadpisania szablonów po aktualizacjach motywu nadrzędnego lub niekompletny theme.yml w motywie potomnym powodujący znikanie modułów z hooków.

Przy aktualizacji PrestaShop sprawdź changelog pod kątem zmian w szablonach. Nadpisania szablonów w motywie potomnym wymagają aktualizacji po zmianach w motywie nadrzędnym.

8. Kompatybilność wersji PHP

Macierz kompatybilności

* PS 1.7.8 ma częściowe wsparcie PHP 8.0 — rdzeń działa, ale wiele modułów nie.

Typowe błędy przy aktualizacji

• PHP 7.x → 8.0: TypeError: expects string, null given — PHP 8 jest rygorystyczny wobec null w strlen(), strpos(), itp.
• PHP 8.0 → 8.1: Return type should be compatible — bardziej rygorystyczne typy. FILTER_SANITIZE_STRING zdeprecjonowane.
• PHP 8.1 → 8.2: Dynamiczne właściwości zdeprecjonowane.

Ważne: Wersje PHP z linii poleceń i z serwera web mogą się różnić na serwerach z wieloma wersjami PHP. Zawsze sprawdzaj przez phpinfo() w przeglądarce, nie tylko php -v. Przed aktualizacją: przetestuj na środowisku testowym, uruchom php -l na plikach modułów, najpierw zaktualizuj moduły.

9. E-maile się nie wysyłają

• Test z panelu administracyjnego: Advanced Parameters → Email → "Send a test email."
• Sprawdź ustawienia SMTP: Host, port (587/TLS lub 465/SSL), nazwa użytkownika, hasło.
• Sprawdź tabelę ps_mail: Jeśli e-maile pojawiają się tutaj, PS je wysłał — problem leży w dostarczaniu.
• PHP mail(): Jeśli nie działa, przełącz na SMTP — bardziej niezawodne wszędzie.
• Rekordy DNS: SPF, DKIM, DMARC są wymagane do współczesnego dostarczania e-maili.

Pełny poradnik: PrestaShop Email Deliverability.

10. Nagły spadek wydajności

Szybka diagnostyka

Sprawdź przestrzeń dyskową (df -h), obciążenie serwera (uptime), MySQL (SHOW FULL PROCESSLIST) i status OPcache. Pełne dyski powodują ciche awarie wszystkiego.

Typowe nagłe spowolnienia

• Tryb debugowania pozostawiony włączony: Sprawdź _PS_MODE_DEV_ w pierwszej kolejności. To rozwiązuje więcej skarg na "wolny sklep" niż cokolwiek innego.
• Pełny dysk: MySQL się zawiesza, cache nie może zapisywać, logi nie mogą się rotować.
• Złe zapytanie modułu: Jedno zapytanie bez indeksu na dużej tabeli może dodać sekundy do każdego ładowania strony.
• Nakładające się zadania cron: Wiele skryptów importu/indeksowania działających równocześnie.
• Rozdęte tabele: ps_connections, ps_log, ps_cart rosną w nieskończoność bez konserwacji.

Pełny poradnik: PrestaShop Performance Optimization.

11. Popularne komunikaty błędów — wyjaśnienie

"Class 'SomeClass' not found"

Usuń var/cache/prod/class_index.php (regeneruje się automatycznie), uruchom composer dump-autoload (PS 1.7+) i sprawdź wielkość liter w nazwach plików na Linuksie. Jeśli moduł został częściowo usunięty, wyczyść tabele ps_hook_module i ps_module.

"CSRF token error" / "Invalid token"

Wygasła sesja (zwiększ session.gc_maxlifetime), wiele kart panelu administracyjnego (odśwież), reverse proxy usuwające ciasteczka (wyłącz panel administracyjny z cache) lub zły zegar serwera.

"Ajax error"

Otwórz DevTools (F12) → zakładka Network. Odtwórz błąd. Znajdź nieudane żądanie (czerwone, status 500). Zakładka Response pokazuje rzeczywisty błąd PHP.

"Allowed memory size exhausted"

Ustaw memory_limit = 512M w php.ini lub .htaccess. Jeśli sklep ciągle potrzebuje więcej, to wyciek pamięci w module — użyj profilera Symfony, aby znaleźć winowajcę.

"Duplicate entry for key"

Naruszenie ograniczenia unikalności. Typowe przy importach produktów (zduplikowane referencje), instalacjach modułów na multistore lub ponownym uruchomieniu nieudanych aktualizacji.

"Deprecated: ..." — zalew komunikatów

To ostrzeżenie, nie błąd. Wycisz: error_reporting = E_ALL & ~E_DEPRECATED. Lepiej: zaktualizuj moduł. Te ostrzeżenia stają się błędami krytycznymi w następnej wersji PHP.

12. Awaryjne odzyskiwanie

Reset hasła administratora

Dla PS 1.6/1.7 (hashowanie MD5):

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

Dla PS 8+/9 (bcrypt), wgraj tymczasowy skrypt PHP, który załaduje config/config.inc.php, użyje PrestaShop\Core\Crypto\Hashing do wygenerowania hasha, zaktualizuje ps_employee, a następnie natychmiast usuń skrypt.

Usuń skrypt resetujący natychmiast po użyciu. Każdy, kto go znajdzie, może zresetować hasło dowolnego administratora.

Wyłączanie uszkodzonego modułu

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

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

Aby wyłączyć wszystkie moduły firm trzecich naraz, zaktualizuj ps_module ustawiając active = 0 dla wszystkich wpisów, których nazwa NIE znajduje się na liście natywnych modułów PS (ps_banner, ps_categorytree, ps_facetedsearch, itp.).

Wyłączanie override

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

Przywracanie z kopii zapasowej

Przełącz stronę w tryb offline, przywróć bazę danych (mysql -u root -p db < backup.sql), przywróć pliki, wyczyść wszystkie warstwy cache (rm -rf var/cache/*), zresetuj OPcache, a następnie zweryfikuj, że strona główna, strona produktu, koszyk, kasa i panel administracyjny działają.

Tryb konserwacji bez panelu administracyjnego

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

13. Lista kontrolna diagnostyki

Wydrukuj to i pracuj od góry do dołu, gdy coś pójdzie nie tak.

Faza 1: Zbieranie informacji

• Co się zmieniło? Instalacja/aktualizacja modułu, aktualizacja PS, aktualizacja PHP, zmiana serwera, edycja motywu?
• Kiedy dokładnie się zaczęło? Porównaj z logami wdrożeń i zadaniami cron.
• Kogo dotyczy? Wszystkich użytkowników, konkretne przeglądarki, tylko panel administracyjny, tylko front sklepu?
• Jaki jest dokładny błąd? Włącz tryb debugowania. Sprawdź konsolę przeglądarki. Sprawdź wszystkie logi.

Faza 2: Izolacja

• Serwer: przestrzeń dyskowa (df -h), pamięć (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP: wersja (php -v), sprawdzenie składni (php -l), ustawienia (phpinfo())
• Cache: wyczyść wszystkie warstwy — Smarty, Symfony, OPcache, przeglądarka. Przetestuj w trybie incognito.
• Moduły: wyłącz ostatnio zmienione. Jeśli nie wiadomo które, wyłącz wszystkie firm trzecich i włączaj po jednym.
• Motyw: tymczasowo przełącz na domyślny.
• Baza danych: mysqlcheck, log błędów MySQL, porównaj struktury tabel jeśli to po aktualizacji.
• Uprawnienia: ls -la na var/cache, var/logs, img, upload.

Faza 3: Naprawa i weryfikacja

• Wprowadzaj JEDNĄ zmianę naraz. Testuj. Jeśli nie naprawiła, cofnij i spróbuj następnej.
• Wyczyść wszystkie warstwy cache po każdej poprawce.
• Testuj dokładnie: stronę główną, kategorię, produkt, koszyk, kasę, panel administracyjny.
• Testuj w trybie incognito / innej przeglądarce.
• Wyłącz tryb debugowania. Usuń tymczasowe skrypty.

Faza 4: Zapobieganie nawrotom

• Udokumentuj, co się stało i co to naprawiło.
• Skonfiguruj monitoring: dostępność, logi błędów, przestrzeń dyskowa.
• Zweryfikuj, że kopie zapasowe działają. Przetestuj przywracanie.

Szybki podręcznik

Lokalizacje logów

• 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: per error_log in php.ini

Kluczowe pliki

• config/defines.inc.php — tryb debugowania, przełącznik override
• app/config/parameters.php — dane logowania do bazy, sekret (PS 1.7+)
• .env / .env.local — środowisko i debugowanie (PS 8+)
• .htaccess — przepisywanie URL, ustawienia PHP, zabezpieczenia

Podstawowe polecenia CLI (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

Każda sesja rozwiązywania problemów zaczyna się tak samo: sprawdź błąd, sprawdź logi, wyizoluj przyczynę. Najbardziej doświadczeni programiści nie zapamiętują każdego błędu — wiedzą, gdzie szukać. Ten poradnik podpowiada Ci te lokalizacje.