Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Laravel or PHP cannot connect to MySQL: [2002] Connection refused

ErrorSQLSTATE[HY000] [2002] Connection refused

Short answer

Error 2002 means no MySQL server answered at the address PHP used. Either the server is stopped, or PHP looked in the wrong place. Check that mysqld runs, then match DB_HOST, DB_PORT and DB_SOCKET to how it listens. The host name localhost means a Unix socket, 127.0.0.1 means TCP.

  • Applies to Laravel 12, PHP 8.3, MySQL 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the server directly over TCP and over the socket. Whichever one answers tells you what PHP must use.

    mysqladmin -h 127.0.0.1 version
    mysqladmin -h localhost version
  2. 2Match what you see, then jump to its fix

    1. 1Both mysqladmin commands fail, and no mysqld process existsMySQL is not runningFix
    2. 2mysqladmin -h 127.0.0.1 works, the localhost form failsDB_HOST is localhost, so PHP uses a socket that is not where MySQL put itFix
    3. 3Connection refused on 127.0.0.1, while the server is runningThe port in DB_PORT is not the port MySQL listens onFix
    4. 4Works on the database machine, refused from the app machine or containerThe server does not accept TCP from where you connectFix

What does the error look like?

  • SQLSTATE[HY000] [2002] Connection refused
  • PHP Connection failed: SQLSTATE[HY000] [2002] Connection refused
  • mysqli_connect(): (HY000/2002): No connection could be made because the target machine actively refused it

Cause 1 of 4

MySQL is not running

1Check

Look for a mysqld process, or for your local stack's own service (MAMP, XAMPP, WAMP, Homestead, Docker).

ps xa | grep mysqld

2Fix

Start the server from its own control panel or service manager. If it dies again at once, read its error log, because the start-up failure is the real problem.

sudo systemctl start mysql

3Verify

mysqladmin answers with the server version.

mysqladmin -h 127.0.0.1 version

Confirmed by dev.mysql.com

Did this fix it?

Cause 2 of 4

DB_HOST is localhost, so PHP uses a socket that is not where MySQL put it

1Check

With host=localhost the PDO MySQL driver connects through a Unix domain socket, not TCP. MAMP and some Docker or Homestead layouts keep the socket in a different path than PHP expects.

mysql -u root -p -e "SHOW VARIABLES LIKE 'socket';"
php -i | grep -i default_socket

2Fix

Either connect over TCP with 127.0.0.1, or give Laravel the real socket path in DB_SOCKET.

# .env, option A: TCP
DB_HOST=127.0.0.1
DB_PORT=3306

# .env, option B: socket (path from SHOW VARIABLES)
DB_SOCKET=/path/to/mysql.sock

3Verify

Clear the config cache and run a migration status check.

php artisan config:clear
php artisan migrate:status

Confirmed by php.net

Did this fix it?

Cause 3 of 4

The port in DB_PORT is not the port MySQL listens on

1Check

A second MySQL copy, or a local stack, can listen on another port. Ask the running server which one it uses.

mysql -u root -p -e "SHOW VARIABLES LIKE 'port';"
grep '^DB_PORT' .env

2Fix

Put the server's real port in DB_PORT.

DB_PORT=3306   # use the value SHOW VARIABLES printed

3Verify

Connect with that port explicitly.

mysqladmin -h 127.0.0.1 -P 3306 version

Confirmed by dev.mysql.com

Did this fix it?

Cause 4 of 4

The server does not accept TCP from where you connect

1Check

skip_networking turns TCP off. bind_address=127.0.0.1 accepts local clients only. A firewall can also block port 3306.

mysql -u root -p -e "SHOW VARIABLES WHERE Variable_name IN ('skip_networking','bind_address','port');"

2Fix

Set bind_address in the MySQL config to an address the app can reach (or 0.0.0.0 behind a firewall), leave skip_networking off, and open port 3306 only to the app host. Restart MySQL after the change.

# my.cnf, [mysqld] section
bind_address = 0.0.0.0

3Verify

From the app machine, try the port.

mysqladmin -h DB_HOST_VALUE version

Confirmed by dev.mysql.com

Did this fix it?

How do I stop it coming back?

  • Use 127.0.0.1 and an explicit DB_PORT in .env for local work, so socket paths never matter.
  • Check the database with mysqladmin before you debug the PHP code.
  • Keep one MySQL instance per machine, or give each its own port and write the port down in .env.example.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.