Laravel or PHP cannot connect to MySQL: [2002] Connection refused
SQLSTATE[HY000] [2002] Connection refusedShort 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.
Fix it fast
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 version2Match what you see, then jump to its fix
- 1
Both mysqladmin commands fail, and no mysqld process existsMySQL is not runningFix - 2
mysqladmin -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
Connection refused on 127.0.0.1, while the server is runningThe port in DB_PORT is not the port MySQL listens onFix - 4
Works on the database machine, refused from the app machine or containerThe server does not accept TCP from where you connectFix
- 1
What does the error look like?
SQLSTATE[HY000] [2002] Connection refusedPHP Connection failed: SQLSTATE[HY000] [2002] Connection refusedmysqli_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 mysqld2Fix
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 mysql3Verify
mysqladmin answers with the server version.
mysqladmin -h 127.0.0.1 versionConfirmed by dev.mysql.com
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_socket2Fix
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.sock3Verify
Clear the config cache and run a migration status check.
php artisan config:clear
php artisan migrate:statusConfirmed by php.net
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' .env2Fix
Put the server's real port in DB_PORT.
DB_PORT=3306 # use the value SHOW VARIABLES printed3Verify
Connect with that port explicitly.
mysqladmin -h 127.0.0.1 -P 3306 versionConfirmed by dev.mysql.com
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.03Verify
From the app machine, try the port.
mysqladmin -h DB_HOST_VALUE versionConfirmed by dev.mysql.com
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:
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
- EZ EstimaterConstruction quoting and job tracking for contractors, on a Laravel and Firebase stack.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
Related fixes
Back end
Laravel cannot log in to MySQL: Access denied for user
SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost' (using password: NO)
Error 1045 means MySQL received the login and rejected it.
4 causes, each with a fixBack end
Laravel insert fails with 'Field user_id doesn't have a default value'
The insert works when the column is removed or made nullable
Error 1364 means Laravel sent an INSERT without a value for a NOT NULL column that has no default, and MySQL strict mode refuses it.
3 causes, each with a fixBack end
Laravel migration cannot drop a column that has a foreign key
Error on rename of '%s' to '%s' (errno: %d - %s)
MySQL refuses to drop a column while a foreign key constraint still uses it.
2 causes, each with a fixBack end
Laravel: distinct() and count() give the total instead of the unique count
select('city')->distinct()->count() ignores the select
Laravel builds the count from the column you pass to count(), not from select().
2 causes, each with a fixBack end
Laravel Eloquent query for a column that is X or NULL
where('column', null) returns no rows
Wrap the pair in a closure: where(function ($q) { $q->where('col', $x)->orWhereNull('col'); }).
3 causes, each with a fixBack end
Laravel insert fails with Invalid datetime format 1292 Incorrect datetime value
SQLSTATE[22007]: Invalid datetime format: 1292 Incorrect datetime value
MySQL ran in strict mode and refused a date or time value that it cannot store.
3 causes, each with a fix