WordPress — debug i troubleshooting błędów
Opublikowano: 9 kwietnia 2026 · Kategoria: WordPress
Biały ekran, błąd 500, baza danych niedostępna — WordPress potrafi zepsuć się w najmniej odpowiednim momencie. Ten przewodnik pokazuje systematyczną diagnostykę: od włączenia logów po identyfikację winowajcy wśród wtyczek, z konkretnymi komendami i ścieżkami plików.
Włączenie WP_DEBUG — pierwsza linia diagnozy
Plik wp-config.php w katalogu głównym WordPress zawiera stałe sterujące debugowaniem.
Domyślnie są wyłączone. Aby włączyć tryb debug z zapisem do pliku (bezpieczne na produkcji — błędy
nie są widoczne dla użytkowników):
// wp-config.php — dodaj PRZED linią "That's all, stop editing!" // Włącz tryb debugowania define( 'WP_DEBUG', true ); // Zapisuj błędy do pliku zamiast wyświetlać na ekranie define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); // Wyłącz cache zapytań (pomocne przy diagnostyce DB) define( 'SAVEQUERIES', true ); // Zwiększ limit pamięci PHP dla WP define( 'WP_MEMORY_LIMIT', '256M' );
Logi trafiają do wp-content/debug.log. Możesz je podglądać na bieżąco przez
SSH:
# Obserwuj logi w czasie rzeczywistym tail -f wp-content/debug.log # Pokaż ostatnie 50 linii tail -n 50 wp-content/debug.log # Szukaj fatal errorów grep -i "fatal\|error\|warning" wp-content/debug.log | tail -20
Query Monitor — debugowanie w panelu admina
Plugin Query Monitor (darmowy, wordpress.org) to najwygodniejsze narzędzie do diagnostyki działającego WordPressa. Wyświetla w pasku admina:
- Wszystkie zapytania SQL z czasem wykonania i źródłem (która wtyczka/motyw)
- PHP errors, warnings i notices z pełnym stack trace
- Wolne zapytania (slow queries) i duplikaty
- Błędy hooków i filtrów
- Czas ładowania strony i zużycie pamięci
- Zmienne środowiskowe PHP i stałe WordPress
Query Monitor jest bezpieczny na produkcji — dane widzi tylko zalogowany administrator. Niezbędny przy diagnozowaniu problemów z wydajnością.
Biały ekran śmierci (White Screen of Death)
Biały ekran (lub ekran z komunikatem "There has been a critical error") to najczęstszy objaw fatal erroru PHP. Diagnozuj w tej kolejności:
# Krok 1: Sprawdź debug.log tail -50 wp-content/debug.log # Krok 2: Sprawdź logi PHP serwera # Na Apache/cPanel: tail -50 /var/log/apache2/error.log # Na Nginx: tail -50 /var/log/nginx/error.log # Krok 3: Wyłącz wszystkie wtyczki przez FTP/SFTP # Zmień nazwę katalogu: plugins/ → plugins_disabled/ # Jeśli strona wróciła — problem w jednej z wtyczek # Krok 4: Przywróć motyw domyślny przez FTP # Zmień nazwę katalogu motywu w wp-content/themes/
Jeśli masz dostęp WP-CLI, możesz wyłączyć wtyczki bez FTP:
# Wyłącz wszystkie wtyczki wp plugin deactivate --all # Aktywuj po jednej i testuj wp plugin activate woocommerce wp plugin activate contact-form-7 # Sprawdź motyw wp theme activate twentytwentyfour
500 Internal Server Error — diagnostyka
Błąd 500 może mieć wiele przyczyn. Sprawdź w tej kolejności:
| Przyczyna | Diagnoza | Rozwiązanie |
|---|---|---|
| Błąd w .htaccess | Zmień nazwę .htaccess na .htaccess_old | Wygeneruj nowy: Ustawienia → Bezpośrednie odnośniki → Zapisz |
| Zbyt duże zużycie PHP | PHP fatal error w logach serwera | Zwiększ memory_limit i max_execution_time w php.ini |
| Błędna wersja PHP | php -v vs wymagania wtyczki | Zmień wersję PHP w panelu hostingu |
| Wtyczka z błędem | debug.log z fatal error i nazwą pliku | Wyłącz wtyczkę przez FTP lub WP-CLI |
| Pełny dysk | df -h na serwerze | Usuń zbędne pliki, wyczyść logi, skompresuj backupy |
"Error establishing a database connection"
Ten komunikat oznacza że WordPress nie może połączyć się z MySQL/MariaDB. Sprawdź:
# Krok 1: Sprawdź dane w wp-config.php grep -E "DB_NAME|DB_USER|DB_PASSWORD|DB_HOST" wp-config.php # Krok 2: Testuj połączenie ręcznie mysql -u TWOJ_UZYTKOWNIK -p -h localhost TWOJA_BAZA # Krok 3: Sprawdź stan serwera MySQL systemctl status mysql # lub systemctl status mariadb # Krok 4: Napraw tabele przez WP-CLI wp db check wp db repair # Krok 5: Sprawdź liczbę połączeń mysql -e "SHOW STATUS LIKE 'Threads_connected';" mysql -e "SHOW VARIABLES LIKE 'max_connections';"
Na hostingu współdzielonym DB_HOST to często nie localhost ale np. mysql.twojadomena.pl — sprawdź w panelu hostingu. Przy zbyt wielu równoczesnych połączeniach
hostingodawca może blokować nowe — skontaktuj się z supportem.
Memory limit PHP — diagnoza i naprawa
# Sprawdź aktualny limit w WordPress
wp eval "echo WP_MEMORY_LIMIT;"
wp eval "echo ini_get('memory_limit');"
# Ustaw limit w wp-config.php
# define( 'WP_MEMORY_LIMIT', '256M' );
# Lub w .htaccess (jeśli hosting pozwala)
# php_value memory_limit 256M
# Lub w php.ini / .user.ini
# memory_limit = 256M WordPress wymaga minimum 64 MB, WooCommerce — 128 MB, duże sklepy — 256 MB lub więcej. Jeśli hosting narzuca niższy limit i nie pozwala go zmienić, rozważ migrację do dostawcy z wyższym memory_limit lub na VPS.
Health Check — panel diagnostyczny WordPress
WordPress od wersji 5.2 ma wbudowany panel diagnostyczny. Przejdź do Narzędzia → Zdrowie witryny. Panel sprawdza:
- Wersję PHP, MySQL i WordPress
- Limity PHP (memory, upload, max_execution_time)
- Status HTTPS i certyfikatu SSL
- Dostępność API REST i loopback connections
- Nieaktualne wtyczki i motywy
- Wymagane rozszerzenia PHP (curl, mbstring, imagick)
Zakładka Informacje o witrynie zawiera pełen raport techniczny — przydatny przy kontakcie z supportem hostingu.
WP-CLI — diagnostyka z linii komend
# Status instalacji wp core verify-checksums # Sprawdź integralność plików WP wp core check-update # Dostępne aktualizacje # Baza danych wp db check # Sprawdź integralność tabel wp db repair # Napraw uszkodzone tabele wp db optimize # Optymalizuj tabele (usuń overhead) # Wtyczki i motywy wp plugin list --status=active wp plugin verify-checksums # Wykryj zmodyfikowane pliki wtyczek wp theme list # Cache wp cache flush # Wyczyść object cache wp rewrite flush # Przebuduj .htaccess / reguły rewrite # Użytkownicy wp user list wp user get admin # Sprawdź uprawnienia administratora