SQLSTATE[HY000] [2002] 🐘 PHP

PDOException: SQLSTATE[HY000] [2002] Connection refused

PHP couldn’t reach the database server at the host/port in your DSN.

Seen on: PHP

Meaning

“Connection refused” means nothing listens there; “No such file or directory” means the Unix socket wasn’t found (host=localhost). In Docker the DB is another container, not localhost.

Common causes

  • Database server not running
  • Wrong host/port in .env
  • localhost (socket) vs 127.0.0.1 (TCP) mismatch
  • Docker: using localhost instead of the service name

⚡ Quick fix

  1. Start the database service
  2. Try host=127.0.0.1 to force TCP
  3. In Docker Compose use the service name (DB_HOST=db)
  4. Run php artisan config:clear after changing .env (Laravel)

Detailed fix by platform

PHP

  1. Test with a tiny script: new PDO('mysql:host=127.0.0.1;dbname=app', 'user', 'pass');

How to diagnose

  1. Server — Is MySQL/PostgreSQL running?
  2. Address — Host and port in the DSN
  3. Network — Container/firewall in between?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.