Situs WordPress yang mati setelah upload plugin atau theme hampir selalu bisa dipulihkan dalam hitungan menit tanpa perlu restore backup penuh: cukup ganti nama folder plugin atau theme yang terakhir masuk, lalu situs langsung hidup kembali. Setelah situs hidup, baru baca log PHP untuk tahu penyebab persisnya, apakah fatal error deklarasi fungsi, kehabisan memori, atau paket ZIP yang ter-upload setengah. Artikel ini membahas urutan diagnosa yang benar supaya Anda tidak menebak-nebak dan tidak menghapus data yang seharusnya masih bisa diselamatkan.
Ringkasan Cepat
- Sekitar 9 dari 10 kasus white screen setelah upload plugin/theme berakar pada folder yang belum lengkap ter-ekstrak atau fatal error di file utama plugin.
- Rename folder lebih aman daripada hapus folder karena konfigurasi dan data plugin tetap tersimpan bila nanti ingin dianalisis.
- Kode 502 dan 504 bukan salah plugin secara langsung, melainkan proses PHP-FPM yang mati di tengah eksekusi karena timeout atau kehabisan memori.
- File .maintenance yang tertinggal adalah penyebab paling sering dari pesan 'Briefly unavailable for scheduled maintenance'.
Akar Masalah: Kenapa Upload Plugin Bisa Mematikan Seluruh Situs
WordPress memuat semua plugin aktif secara berurutan di setiap request, sebelum theme dirender. Artinya satu file plugin yang mengandung syntax error, memanggil class yang tidak ada, atau mendeklarasikan ulang fungsi yang sudah dipakai plugin lain akan menghentikan eksekusi PHP secara total. Karena output belum sempat dikirim ke browser, yang muncul adalah halaman putih atau kode 500 dari web server, bukan pesan error yang informatif.
Ada empat pola kegagalan yang paling sering ditemui di lapangan:
1. Paket ZIP ter-upload tidak utuh
Ini terjadi ketika ukuran file melebihi batas upload PHP. Proses unzip berjalan setengah jalan, folder plugin terbentuk tapi file inti seperti file utama plugin atau direktori includes tidak lengkap. WordPress mendeteksi folder plugin aktif dengan header tidak valid, dan pada beberapa kasus tetap mencoba memuatnya. Hasilnya fatal error 'failed opening required file'.
2. Ketidakcocokan versi PHP
Plugin lama yang memakai fungsi deprecated seperti create_function atau kurung kurawal untuk akses array akan langsung error di PHP 8.1 ke atas. Tidak ada pesan ramah, hanya fatal error di log.
3. Konflik deklarasi fungsi antar plugin
Dua plugin yang mendeklarasikan nama fungsi identik tanpa pengecekan function_exists akan memicu 'Cannot redeclare function'. Ini biasanya muncul setelah plugin baru diinstal, bukan saat instalasi itu sendiri.
4. Theme dengan functions.php bermasalah
Theme yang diubah manual lalu di-upload ulang lewat panel sering kehilangan fileasset atau meninggalkan referensi ke file yang sudah dihapus. Fatal error-nya baru muncul saat template dirender.
Langkah 1: Mode Darurat, Pulihkan Situs dalam Satu Menit
Jangan panik dan jangan langsung restore backup. Akses dulu lewat SSH atau File Manager panel hosting. Prinsipnya sederhana: nonaktifkan komponen yang baru masuk dengan cara mengganti nama foldernya.
Cek dulu plugin mana yang paling baru diubah timestamp-nya:
cd /home/username/public_html/wp-content/plugins
ls -lt --time-style=+%Y-%m-%d_%H:%M | head -n 15Lalu nonaktifkan folder yang mencurigakan dengan mengganti namanya. WordPress hanya memuat folder yang nama direktorinya cocok dengan slug plugin, jadi penambahan akhiran sudah cukup untuk menonaktifkannya secara paksa:
mv nama-plugin nama-plugin.off
# Jika sumber masalah ada di theme:
cd /home/username/public_html/wp-content/themes
mv nama-theme nama-theme.offSetelah rename theme, WordPress akan otomatis jatuh ke theme default yang tersedia. Jika tidak ada theme lain, aktifkan theme bawaan lewat WP-CLI:
cd /home/username/public_html
wp theme activate twentytwentyfour --allow-root
wp plugin list --status=active --allow-rootJika hanya satu plugin yang bermasalah dan Anda ingin menonaktifkannya tanpa menyentuh folder, perintah berikut lebih rapi:
wp plugin deactivate nama-plugin --allow-root
# Nonaktifkan seluruh plugin sekaligus untuk isolasi total:
wp plugin deactivate --all --allow-rootLangkah 2: Bersihkan Sisa Proses Upload yang Gagal
WordPress membuat file .maintenance di root instalasi saat proses update atau instalasi berjalan. Jika proses itu mati di tengah jalan, file tersebut tertinggal dan seluruh situs menampilkan pesan 'Briefly unavailable for scheduled maintenance' meskipun tidak ada proses apa pun yang berjalan.
ls -la /home/username/public_html/.maintenance
rm -f /home/username/public_html/.maintenancePeriksa juga folder wp-content/upgrade dan wp-content/uploads yang sering menyisakan file sementara berukuran besar dari proses unzip yang gagal. File-file ini tidak berbahaya tapi menghabiskan kuota disk.
Langkah 3: Identifikasi Kode Error dan Sumbernya
Kode HTTP yang muncul di browser bukan diagnosis akhir, melainkan petunjuk arah. Tabel berikut memetakan gejala ke lapisan yang bermasalah.
| Gejala | Lapisan Bermasalah | Tindakan Pertama |
|---|---|---|
| 500 Internal Server Error | PHP fatal error di plugin atau theme | Rename folder plugin terbaru, baca PHP error log |
| 502 Bad Gateway | PHP-FPM mati mendadak, biasanya kehabisan memori | Cek log FPM, naikkan memory_limit |
| 504 Gateway Timeout | Proses unzip atau instalasi melebihi batas waktu | Naikkan max_execution_time dan timeout proxy |
| 403 Forbidden | Permission folder salah atau aturan keamanan memblokir | Set folder 755, file 644, cek mod_security |
| Halaman putih tanpa kode | display_errors mati, error tetap tercatat di log | Aktifkan WP_DEBUG_LOG |
| PCLZIP_ERR_BAD_FORMAT | Arsip ZIP korup atau terpotong saat upload | Upload ulang lewat FTP, ekstrak manual |
Langkah 4: Baca Log di Tempat yang Benar
Banyak admin hanya melihat panel WordPress dan menyimpulkan tidak ada error. Padahal error tercatat di dua tempat berbeda: log PHP dari web server, dan log milik WordPress sendiri.
Aktifkan pencatatan error di file wp-config.php, tepat di atas baris 'That is all, stop editing':
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);Setelah itu reproduksi error dengan mengakses halaman yang bermasalah, lalu baca hasilnya:
tail -n 80 /home/username/public_html/wp-content/debug.log
tail -n 80 /home/username/logs/error_log
# Untuk server dengan Nginx + PHP-FPM:
grep -i 'fatal\|memory' /var/log/nginx/error.log | tail -n 40
journalctl -u php8.2-fpm --since '15 min ago'Baris yang perlu Anda cari biasanya berbentuk 'PHP Fatal error: Allowed memory size of X bytes exhausted' atau 'PHP Fatal error: Uncaught Error: Call to undefined function'. Nama file dan nomor baris di pesan itu langsung menunjuk plugin mana yang harus dinonaktifkan.
Langkah 5: Perbaiki Batas Upload dan Memori
Jika error muncul justru saat proses upload berjalan, penyebabnya bukan kode plugin, melainkan konfigurasi PHP yang terlalu ketat. Nilai berikut adalah titik awal yang wajar untuk situs WordPress dengan plugin standar.
| Parameter | Lokasi Konfigurasi | Nilai Aman |
|---|---|---|
| upload_max_filesize | php.ini atau .user.ini | 64M |
| post_max_size | php.ini atau .user.ini | 64M |
| memory_limit | php.ini atau wp-config.php | 256M |
| max_execution_time | php.ini | 300 |
| client_max_body_size | Nginx server block | 64m |
Nilai post_max_size harus selalu lebih besar atau sama dengan upload_max_filesize, karena body request membawa metadata selain file itu sendiri. Untuk Nginx, jangan lupa menaikkan batas body di level server block:
server {
client_max_body_size 64m;
client_body_timeout 300s;
fastcgi_read_timeout 300s;
}Untuk Apache, gunakan file .htaccess di root instalasi:
php_value upload_max_filesize 64M
php_value post_max_size 64M
php_value memory_limit 256M
php_value max_execution_time 300Pastikan juga request_terminate_timeout di pool PHP-FPM tidak lebih kecil dari max_execution_time. Jika nilainya 30 detik sementara PHP butuh 120 detik untuk unzip, proses akan dibunuh dan muncul 502 meskipun kode plugin sepenuhnya sehat.
Langkah 6: Benahi Permission dan Kepemilikan File
Upload plugin lewat panel berjalan sebagai user web server. Jika ekstraksi ZIP menghasilkan file milik user yang salah, WordPress tidak bisa menulis atau membaca file tersebut dan melempar 403 atau error 'failed to open stream'. Standar yang aman untuk WordPress adalah folder 755, file 644, dan kepemilikan sesuai user akun hosting.
cd /home/username/public_html
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chown -R username:username /home/username/public_html
# Verifikasi hasilnya:
ls -ld wp-content wp-content/plugins wp-content/themesHindari penggunaan chmod 777 sebagai jalan pintas. Selain melanggar praktik keamanan dasar, banyak panel hosting modern otomatis menolak eksekusi file dengan permission tersebut sehingga masalah justru berubah bentuk menjadi 403 yang lebih sulit dilacak.
Langkah 7: Upload Manual Saat Panel Terus Gagal
Jika proses upload lewat dashboard selalu berhenti di 99 persen atau menghasilkan PCLZIP_ERR_BAD_FORMAT, lewati panel sepenuhnya. Ekstrak paket ZIP di komputer, lalu unggah foldernya lewat SFTP ke wp-content/plugins. Untuk server Linux, cara ini jauh lebih cepat dan bisa diverifikasi:
cd /home/username/public_html/wp-content/plugins
wget https://downloads.wordpress.org/plugin/nama-plugin.latest-stable.zip
unzip nama-plugin.latest-stable.zip
rm nama-plugin.latest-stable.zip
chown -R username:username nama-pluginSetelah folder berada di tempatnya, aktifkan lewat WP-CLI supaya Anda bisa langsung melihat output error di terminal bila plugin gagal dimuat:
wp plugin activate nama-plugin --allow-root
wp plugin verify-checksums nama-plugin --allow-rootPerintah verify-checksums membandingkan file plugin dengan versi resmi di repositori WordPress. Jika ada file yang hilang atau berubah, hasilnya akan langsung terlihat.