Server Solusi – Ketika Nginx tidak bisa terhubung ke PHP-FPM, website berbasis PHP bisa menampilkan 502 Bad Gateway, 504 Gateway Time-out, atau gagal memproses halaman dinamis. Masalah ini cukup membingungkan karena Nginx bisa saja tetap berstatus aktif, sementara permintaan PHP tidak berhasil diteruskan ke backend.

Penyebabnya tidak selalu PHP-FPM yang mati. Bisa juga socket Unix tidak ditemukan, alamat fastcgi_pass tidak sesuai, permission socket bermasalah, atau proses PHP-FPM membutuhkan waktu terlalu lama untuk merespons.

Saya menyarankan kamu memeriksa hubungan antara Nginx dan PHP-FPM terlebih dahulu sebelum mengubah konfigurasi atau memasang ulang layanan. Dengan begitu, perbaikan bisa diarahkan pada sumber masalah yang benar.

Bagaimana Mengatasi Nginx Tidak Bisa Terhubung ke PHP-FPM?

Cara mengatasi Nginx tidak bisa terhubung ke PHP-FPM adalah memeriksa status service PHP-FPM, membaca log error Nginx, dan mencocokkan alamat fastcgi_pass dengan socket atau port yang benar-benar digunakan PHP-FPM.

Pada Ubuntu, pemeriksaan awal dapat dilakukan menggunakan perintah berikut:

sudo systemctl status nginx --no-pager -lsudo systemctl status php8.3-fpm --no-pager -lsudo tail -n 100 /var/log/nginx/error.log

Contoh di atas menggunakan PHP-FPM 8.3. Jika server kamu memakai versi lain, ganti php8.3-fpm dengan nama service yang sesuai.

Jika PHP-FPM berhenti, cari penyebabnya melalui status service dan log. Jika service berjalan tetapi Nginx tetap gagal terhubung, periksa socket, permission, serta konfigurasi FastCGI pada situs yang bermasalah.

Gejala dan Penyebab Nginx Gagal Terhubung ke PHP-FPM

Sebelum melakukan perbaikan, perhatikan pesan yang muncul pada log Nginx. Pesan error biasanya memberikan petunjuk apakah masalah berasal dari koneksi, socket, permission, atau respons PHP-FPM.

Pesan tersebut bukan diagnosis final. Sebagai contoh, 502 Bad Gateway dapat terjadi karena PHP-FPM berhenti, tetapi juga bisa muncul akibat konfigurasi FastCGI yang salah atau masalah pada backend.

Baca JugaCara Mengatasi Nginx Address Already in Use di VPS Linux

Proses Diagnosis Nginx dan PHP-FPM

Langkah 1. Periksa status service PHP-FPM

Jalankan:

sudo systemctl status php8.3-fpm --no-pager -l

Perintah tersebut memeriksa status service PHP-FPM 8.3. Jika server kamu menggunakan PHP 8.2 atau 8.4, sesuaikan nama service berdasarkan versi yang terpasang.

Untuk melihat versi PHP CLI yang aktif, kamu bisa menjalankan:

php -v

Namun, versi PHP CLI belum tentu sama dengan versi PHP-FPM yang digunakan oleh Nginx. Karena itu, pastikan nama service dan konfigurasi pool yang aktif sebelum mengambil tindakan.

Jika status PHP-FPM menunjukkan failed, baca log servicenya:

sudo journalctl -u php8.3-fpm -n 100 --no-pager

Cari pesan yang menjelaskan alasan service berhenti, seperti kesalahan konfigurasi pool, kegagalan membuat socket, atau masalah resource. Perbaiki penyebab tersebut terlebih dahulu sebelum mencoba menjalankan PHP-FPM kembali.

Jika statusnya active (running), lanjutkan ke pemeriksaan socket atau port karena service yang aktif belum tentu menggunakan alamat yang sama dengan konfigurasi Nginx.

Langkah 2. Periksa log error Nginx

Jalankan:

sudo tail -n 100 /var/log/nginx/error.log

Perintah ini menampilkan 100 baris terakhir dari log error Nginx pada lokasi standar Ubuntu. Jika server menyimpan log di lokasi berbeda, gunakan path yang sesuai dengan konfigurasi.

Perhatikan pesan yang memuat connect() failed, upstream, atau path socket seperti /run/php/php8.3-fpm.sock.

Contohnya, jika log menyebut No such file or directory pada socket PHP-FPM, periksa apakah file socket tersebut benar-benar tersedia. Jika log menyebut Permission denied, fokuskan pemeriksaan pada user, group, dan permission.

Jangan langsung mengubah konfigurasi sebelum mengetahui pesan yang muncul. Tindakan yang tepat untuk socket yang hilang berbeda dengan penanganan socket yang tidak bisa diakses.

Langkah 3. Periksa konfigurasi fastcgi_pass

Nginx meneruskan permintaan PHP ke PHP-FPM melalui direktif fastcgi_pass. Alamat yang digunakan dapat berupa socket Unix atau koneksi TCP.

Cari konfigurasi tersebut:

sudo grep -RIn "fastcgi_pass" /etc/nginx/

Perintah ini mencari penggunaan fastcgi_pass di direktori konfigurasi Nginx. Periksa file VirtualHost atau server block yang berkaitan dengan domain bermasalah.

Baca JugaCara Memperbaiki Nginx Permission Denied di Linux dan VPS

Contoh konfigurasi menggunakan socket Unix:

location ~ \.php$ {include snippets/fastcgi-php.conf;fastcgi_pass unix:/run/php/php8.3-fpm.sock;}

Contoh lainnya menggunakan TCP:

location ~ \.php$ {include snippets/fastcgi-php.conf;fastcgi_pass 127.0.0.1:9000;}

Kedua contoh tersebut merupakan alternatif, bukan konfigurasi yang harus dipasang sekaligus. Gunakan bentuk yang sesuai dengan pengaturan PHP-FPM pada server kamu.

Jika PHP-FPM mendengarkan socket Unix, tetapi Nginx diarahkan ke port TCP yang tidak digunakan, koneksi akan gagal. Hal yang sama terjadi jika Nginx menunjuk socket dengan nama atau path yang salah.

Langkah 4. Periksa socket atau port PHP-FPM

Jika konfigurasi Nginx menggunakan socket Unix, periksa file socket yang dirujuk:

ls -l /run/php/

Perhatikan apakah socket yang disebutkan dalam fastcgi_pass tersedia. Nama file dapat berbeda sesuai versi PHP dan konfigurasi pool.

Jika menggunakan TCP, periksa port yang sedang mendengarkan:

sudo ss -ltnp | grep ':9000'

Perintah tersebut memeriksa listener TCP pada port 9000. Jika tidak ada output, belum tentu PHP-FPM mati; service mungkin menggunakan port lain atau socket Unix.

Untuk mengetahui alamat listener yang sebenarnya, periksa konfigurasi pool PHP-FPM. Pada instalasi Ubuntu standar, file pool biasanya berada di:

/etc/php/8.3/fpm/pool.d/

Sesuaikan direktori tersebut dengan versi PHP-FPM yang terpasang. Cari direktif listen untuk mengetahui apakah PHP-FPM menggunakan socket atau alamat TCP tertentu.

Cara Memperbaiki Nginx yang Tidak Terhubung ke PHP-FPM

Solusi 1. Jalankan kembali PHP-FPM jika service berhenti

Jika pemeriksaan menunjukkan PHP-FPM memang berhenti, periksa terlebih dahulu penyebabnya melalui log. Setelah penyebab kegagalan ditangani, kamu dapat menjalankan:

sudo systemctl start php8.3-fpm

Perintah ini mencoba memulai service PHP-FPM 8.3. Jika service kembali gagal, jangan mengulanginya terus-menerus tanpa membaca pesan error terbaru.

Periksa statusnya:

sudo systemctl status php8.3-fpm --no-pager -l

Jika sudah active (running), lanjutkan dengan menguji konfigurasi Nginx dan permintaan PHP.

Solusi 2. Samakan path socket Nginx dan PHP-FPM

Jika PHP-FPM berjalan melalui socket Unix, nilai fastcgi_pass harus menunjuk socket yang benar-benar dibuat oleh pool PHP-FPM.

Baca JugaCara Mengatasi Error 504 Gateway Timeout Nginx dengan Tepat

Misalnya, konfigurasi Nginx menggunakan:

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Pastikan konfigurasi pool PHP-FPM memang menggunakan alamat listener yang sesuai. Periksa direktif listen pada file pool yang aktif, bukan hanya nama file socket yang diperkirakan tersedia.

Jika nama socket berbeda, sesuaikan salah satu konfigurasi agar keduanya cocok. Jangan membuat file socket kosong secara manual karena socket harus dibuat oleh proses PHP-FPM.

Setelah perubahan, validasi konfigurasi Nginx:

sudo nginx -t

Jika valid, terapkan perubahan dengan:

sudo systemctl reload nginx

Jika kamu juga mengubah konfigurasi pool PHP-FPM, service PHP-FPM perlu memuat ulang konfigurasi tersebut. Lakukan restart atau reload sesuai kebutuhan dan kondisi server, setelah memeriksa konfigurasi serta mempertimbangkan dampak pada permintaan yang sedang berjalan.

Solusi 3. Perbaiki permission socket

Jika log menunjukkan Permission denied, periksa kepemilikan dan permission socket:

ls -l /run/php/php8.3-fpm.sock

Kemudian periksa user worker Nginx:

ps -eo user,group,comm | grep nginx

Pada konfigurasi Ubuntu yang umum, worker Nginx berjalan menggunakan user www-data, tetapi nilai aktual bergantung pada konfigurasi server.

Periksa pengaturan socket pada file pool PHP-FPM, khususnya:

listen.owner = www-datalisten.group = www-datalisten.mode = 0660

Nilai di atas merupakan contoh yang lazim, bukan nilai universal untuk semua server. Terapkan hanya jika sesuai dengan user dan group yang digunakan Nginx serta kebijakan keamanan server kamu.

Setelah perubahan konfigurasi pool, terapkan konfigurasi PHP-FPM dengan hati-hati. Socket yang dibuat ulang bisa memiliki permission berbeda jika pengaturan pool tidak sesuai.

Hindari mengatasi masalah dengan chmod 777 pada socket atau direktori /run/php/. Akses yang terlalu terbuka tidak diperlukan untuk memperbaiki sebagian besar masalah permission dan dapat mengurangi keamanan server.

Solusi 4. Perbaiki konfigurasi pool PHP-FPM

Jika service PHP-FPM gagal startup, masalahnya bisa berasal dari file pool, bukan Nginx.

Periksa log:

sudo journalctl -u php8.3-fpm -n 100 --no-pager

Jika log menyebut kesalahan konfigurasi, periksa file pool terkait di /etc/php/8.3/fpm/pool.d/. Pastikan nilai listen, nama pool, serta parameter lainnya ditulis dengan benar.

Baca JugaCara Mengatasi Apache Failed to Start di Ubuntu: Diagnosis dan Perbaikan

Pada beberapa instalasi, kamu juga bisa memeriksa konfigurasi PHP-FPM menggunakan:

sudo php-fpm8.3 -t

Perintah ini menguji konfigurasi PHP-FPM 8.3 jika binary tersebut tersedia pada sistem. Sesuaikan nama binary dengan versi yang terpasang.

Jika validasi menemukan kesalahan, perbaiki file yang disebutkan. Jangan mengganti seluruh konfigurasi pool dengan contoh dari server lain karena pengaturan worker, user, dan resource dapat berbeda.

Solusi 5. Tangani PHP-FPM yang kehabisan worker atau lambat merespons

Jika log Nginx menunjukkan upstream timed out, koneksi mungkin berhasil dibuat tetapi PHP-FPM atau aplikasi tidak merespons dalam batas waktu yang ditentukan.

Periksa log PHP-FPM dan log aplikasi untuk melihat apakah terjadi proses PHP yang lambat, query database yang tertahan, atau worker yang mencapai batas kapasitas.

Kamu juga dapat memeriksa kapasitas pool melalui konfigurasi seperti pm.max_children. Namun, jangan langsung menaikkan nilainya tanpa mengevaluasi penggunaan memori. Terlalu banyak worker justru dapat membuat server kehabisan RAM.

Timeout Nginx juga tidak sebaiknya dinaikkan sebagai solusi pertama. Temukan dahulu apakah keterlambatan berasal dari aplikasi, database, atau kapasitas PHP-FPM.

Verifikasi Setelah Perbaikan

Setelah melakukan perubahan, jangan langsung menyimpulkan masalah sudah selesai hanya karena service kembali aktif. Periksa service PHP-FPM, konfigurasi Nginx, dan respons website.

Periksa konfigurasi Nginx

sudo nginx -t

Hasil yang diharapkan adalah pesan bahwa sintaks konfigurasi berhasil diperiksa dan pengujian konfigurasi dinyatakan berhasil. Jika ada error, perbaiki terlebih dahulu sebelum melakukan reload.

Periksa status kedua service

sudo systemctl status nginx --no-pager -lsudo systemctl status php8.3-fpm --no-pager -l

Pastikan kedua service menunjukkan active (running) jika memang keduanya seharusnya berjalan.

Uji respons website

Untuk menguji website melalui HTTP lokal:

curl -I http://127.0.0.1/

Perlu diingat bahwa pengujian ke 127.0.0.1 belum tentu memilih VirtualHost yang sesuai dengan domain kamu. Untuk menguji domain tertentu, gunakan:

curl -I -H "Host: example.com" http://127.0.0.1/

Ganti example.com dengan domain yang dikonfigurasi pada server.

Jika website menggunakan HTTPS atau konfigurasi reverse proxy tertentu, lakukan pengujian tambahan yang sesuai. Respons 200 OK dapat menjadi indikasi bahwa endpoint merespons, tetapi belum menjamin semua halaman PHP berfungsi dengan benar.

Cara Mencegah Masalah Nginx dan PHP-FPM Terulang

Beberapa langkah berikut membantu mengurangi risiko gangguan koneksi antara Nginx dan PHP-FPM.

• Validasi konfigurasi sebelum reload. Jalankan nginx -t setiap kali mengubah konfigurasi Nginx.

• Pantau log kedua service. Log Nginx menunjukkan masalah koneksi upstream, sedangkan log PHP-FPM dapat menjelaskan mengapa backend berhenti atau lambat merespons.

• Dokumentasikan versi PHP-FPM. Catat service, socket, dan file pool yang digunakan setiap website.

• Jaga permission socket tetap sesuai kebutuhan. Pastikan Nginx memiliki akses yang diperlukan tanpa membuka akses berlebihan.

• Pantau penggunaan RAM dan kapasitas worker. Ini penting untuk aplikasi PHP yang memproses banyak permintaan.

• Cadangkan konfigurasi sebelum perubahan besar. Simpan salinan konfigurasi Nginx dan PHP-FPM agar pemulihan lebih mudah dilakukan.

FAQ

Kenapa Nginx menampilkan 502 Bad Gateway saat membuka website PHP?

Salah satu penyebabnya adalah Nginx gagal terhubung ke PHP-FPM. Penyebab lain meliputi socket yang tidak tersedia, permission yang salah, konfigurasi FastCGI yang tidak cocok, atau masalah pada backend PHP.

Bagaimana cara mengetahui socket PHP-FPM yang digunakan?

Periksa direktif listen pada file pool PHP-FPM, lalu cocokkan dengan nilai fastcgi_pass di konfigurasi Nginx. Kamu juga dapat melihat file socket yang tersedia menggunakan ls -l /run/php/.

Apakah Nginx harus direstart setelah PHP-FPM diperbaiki?

Tidak selalu. Jika konfigurasi Nginx tidak berubah, kamu mungkin cukup menjalankan atau memulihkan service PHP-FPM. Jika konfigurasi Nginx diubah, validasi dengan nginx -t, lalu lakukan reload jika hasilnya valid.

Apa perbedaan connection refused dan permission denied?

Connection refused menunjukkan koneksi ditolak pada alamat atau port tujuan, misalnya karena tidak ada listener yang sesuai. Permission denied menunjukkan akses ditolak oleh sistem. Untuk socket Unix, periksa keberadaan socket serta permission dan akses direktori induknya.

Apakah menaikkan timeout Nginx bisa memperbaiki masalah PHP-FPM?

Hanya jika masalahnya berkaitan dengan waktu respons yang terlalu lama dan penyebab keterlambatan memang sudah dipahami. Jika socket tidak tersedia atau koneksi ditolak, menaikkan timeout tidak akan menyelesaikan akar masalah.

Penutup

Jika Nginx tidak bisa terhubung ke PHP-FPM, mulailah dengan membaca log error dan memeriksa status kedua service. Selanjutnya, cocokkan fastcgi_pass dengan alamat listener PHP-FPM, periksa permission socket, dan pastikan konfigurasi tidak memiliki kesalahan.

Jika masalah masih terjadi, gunakan pesan error terbaru sebagai dasar pemeriksaan berikutnya. Jangan langsung mengganti permission, menaikkan timeout, atau memasang ulang layanan tanpa mengetahui penyebabnya.

Referensi Teknis

1. Nginx Documentation — Module ngx_http_fastcgi_module

2. PHP Manual — PHP-FPM Configuration

3. Ubuntu Server Documentation

Catatan: Artikel ini menggunakan skenario umum pada Ubuntu dengan Nginx dan PHP-FPM. Versi PHP, nama service, lokasi socket, dan pengaturan pool perlu disesuaikan dengan konfigurasi aktual server. Tidak ada log server spesifik yang diberikan, sehingga penyebab pastinya harus ditentukan melalui pemeriksaan.