Lewati ke konten
Kelarin Proyek
19 November 2026

Error SQLSTATE[HY000] [2002] dan Solusinya

Arti error SQLSTATE[HY000] [2002] di Laravel dan PHP, serta cara memperbaikinya: cek MySQL, host, port, soket, Docker, dan cache konfigurasi.

Kamu menjalankan aplikasi Laravel, lalu layar menampilkan SQLSTATE[HY000] [2002] Connection refused atau No such file or directory. Aplikasi tidak bisa menjangkau server MySQL sama sekali. Berbeda dari error kata sandi salah, error SQLSTATE[HY000] [2002] berarti sambungan bahkan tidak terbentuk. Artikel ini menunjukkan cara menelusurinya dari penyebab yang paling sering sampai yang jarang, lengkap dengan perintah yang bisa langsung dicoba.

Apa arti kode 2002

Angka 2002 adalah kode kesalahan klien MySQL untuk kegagalan membuka koneksi. Pesan di belakangnya menentukan arah diagnosis:

PesanArti singkat
Connection refusedAda alamat tujuan, tetapi tidak ada yang mendengarkan di port itu
No such file or directoryPHP mencari berkas soket MySQL yang tidak ada di lokasi tersebut
Connection timed outPaket tidak sampai, biasanya karena firewall atau alamat host salah

Jadi sebelum mengubah kode, pastikan dulu tiga hal: MySQL berjalan, alamat dan port yang dipakai benar, dan tidak ada yang memblokir jalur.

Langkah 1: pastikan MySQL benar-benar berjalan

Penyebab paling sering di komputer lokal adalah layanan MySQL belum dinyalakan. Di XAMPP, buka panel dan pastikan modul MySQL berwarna hijau. Di Linux, cek lewat systemd:

sudo systemctl status mysql
sudo systemctl start mysql

Bila statusnya gagal menyala, baca log servernya, misalnya sudo journalctl -u mysql -n 50. Penyebab umum kegagalan start adalah port 3306 sudah dipakai layanan lain atau disk penuh. Di Windows dengan XAMPP, program lain seperti MySQL bawaan sistem sering berbenturan dengan XAMPP, sehingga salah satunya gagal berjalan.

Untuk memastikan ada yang mendengarkan di port 3306:

sudo ss -ltnp | grep 3306

Tidak ada baris keluar berarti tidak ada server MySQL yang menerima sambungan, dan semua langkah selanjutnya tidak ada gunanya sampai ini beres.

Langkah 2: periksa DB_HOST dan DB_PORT di .env

Buka berkas .env dan lihat bagian database:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nama_database
DB_USERNAME=nama_pengguna
DB_PASSWORD=kata_sandi

Ada perbedaan halus antara localhost dan 127.0.0.1. Dengan localhost, klien MySQL di Linux dan macOS mencoba memakai soket Unix, bukan jaringan. Bila lokasi soket default tidak cocok dengan lokasi sebenarnya, kamu mendapat pesan No such file or directory. Mengganti ke 127.0.0.1 memaksa sambungan lewat TCP dan sering langsung menyelesaikan masalah.

Pastikan juga port sesuai. XAMPP kadang diubah ke 3307 untuk menghindari bentrok. Nilai DB_PORT harus sama dengan port yang tampak di perintah ss tadi.

Langkah 3: bersihkan cache konfigurasi

Setelah mengubah .env, Laravel mungkin masih memakai nilai lama dari cache. Gejalanya: kamu sudah memperbaiki host, tetapi pesan error tetap sama.

php artisan config:clear
php artisan cache:clear
php artisan optimize:clear

Ingat bahwa setelah php artisan config:cache, berkas .env tidak lagi dibaca langsung saat permintaan berjalan. Setiap kali mengubahnya di server produksi, jalankan ulang config:cache supaya nilai baru terpakai.

Langkah 4: uji koneksi di luar Laravel

Untuk memisahkan masalah aplikasi dan masalah server, coba sambungkan dari terminal memakai kredensial yang sama.

mysql -h 127.0.0.1 -P 3306 -u nama_pengguna -p

Bila perintah ini berhasil tetapi Laravel gagal, masalahnya ada di konfigurasi aplikasi, misalnya .env yang salah dibaca atau cache lama. Bila perintah ini juga gagal dengan pesan yang sama, masalahnya ada di server atau jaringan, bukan di kode.

Cara lain yang cepat adalah memakai tinker:

php artisan tinker
>>> DB::connection()->getPdo();

Bila koneksi gagal, tinker menampilkan pengecualian dengan pesan yang jelas, jauh lebih mudah dibaca daripada halaman error di peramban.

Langkah 5: kasus Docker dan Laravel Sail

Di Docker, 127.0.0.1 di dalam kontainer aplikasi menunjuk ke kontainer itu sendiri, bukan ke kontainer MySQL. Ini penyebab klasik 2002 pada proyek yang dijalankan dengan Compose. Gunakan nama layanan sebagai host:

DB_HOST=mysql
DB_PORT=3306

Nama mysql harus sama dengan nama layanan di docker-compose.yml. Pastikan juga kontainer database sudah selesai menyala sebelum aplikasi mencoba terhubung, karena MySQL butuh beberapa detik untuk siap. Pada Sail, urutan ini biasanya sudah diatur lewat depends_on dan pemeriksaan kesehatan.

Langkah 6: soket yang salah di macOS dan Linux

Bila kamu tetap ingin memakai localhost, tentukan lokasi soket yang benar. Cari lokasinya dari MySQL:

SHOW VARIABLES LIKE 'socket';

Lalu isi di konfigurasi database Laravel:

DB_SOCKET=/var/run/mysqld/mysqld.sock

Lokasi soket berbeda antar sistem: pada Ubuntu biasanya di /var/run/mysqld/mysqld.sock, sedangkan pada instalasi Homebrew di macOS berada di lokasi lain. Kesalahan lokasi inilah yang memunculkan pesan No such file or directory.

Langkah 7: firewall, host jauh, dan timeout

Bila database berada di server lain, pastikan MySQL menerima sambungan dari luar dan port terbuka. Cek bagian bind-address pada konfigurasi MySQL. Nilai 127.0.0.1 berarti hanya menerima sambungan dari mesin yang sama. Untuk database di server terpisah, gunakan alamat jaringan yang sesuai dan buka port hanya untuk alamat aplikasi, bukan untuk seluruh internet.

sudo ufw allow from 10.0.0.5 to any port 3306

Contoh itu hanya mengizinkan satu alamat tertentu. Membuka port 3306 ke publik adalah praktik berisiko karena server MySQL yang terbuka sering menjadi sasaran percobaan masuk otomatis.

Daftar periksa cepat

  1. Pastikan MySQL berjalan dan mendengarkan di port yang benar.
  2. Ganti DB_HOST menjadi 127.0.0.1, atau nama layanan bila memakai Docker.
  3. Samakan DB_PORT dengan port server.
  4. Jalankan php artisan optimize:clear.
  5. Uji dengan klien mysql di terminal.
  6. Cek soket, firewall, dan bind-address bila database di mesin lain.

Mayoritas kasus 2002 selesai di langkah 1 sampai 3, karena umumnya berasal dari layanan yang belum menyala atau host yang tidak cocok.

Kalau masih buntu

Bila sudah menjalankan semua langkah dan error tetap muncul, kumpulkan bahan yang lengkap: pesan error utuh, isi .env tanpa kata sandi, hasil ss -ltnp | grep 3306, dan lingkunganmu (XAMPP, Docker, atau server). Bahan yang lengkap mempercepat diagnosis. Untuk perbaikan langsung, lihat jasa debugging dan perbaikan error. Aplikasi Laravel yang ingin dikerjakan dari awal bisa lewat jasa Laravel, dan desain tabel atau kueri lewat jasa database MySQL. Siap melanjutkan? Ajukan pesanan dan masalahnya kita tulis dulu di SOW.

Punya proyek? Ngobrol dulu, gratis.