How to Fix SQLSTATE[HY000] [2002] Connection Refused in Laravel

Laravel throws SQLSTATE[HY000] [2002] Connection refused when PHP cannot reach MySQL at all. Here is how to find which of the six usual causes is yours โ€” and fix it for good.

RH Raja HunainAuthor 21 Nov 2026 8 min read 15 views
On this page
Share

Explanation

You run php artisan migrate, open your app in the browser, or deploy to a fresh server โ€” and Laravel answers with this:

Illuminate\Database\QueryException
SQLSTATE[HY000] [2002] Connection refused (Connection: mysql, SQL: ...)

It looks like a database error, but it is not. It is a connection error, and that difference matters, because it tells you exactly where to look. This guide explains what the error means, gives you a 30-second test that separates the causes, and then walks through every fix in the order you should try them.

What This Error Actually Means

The [2002] code comes from the MySQL client library, and it happens before any SQL runs and before your username or password are even checked. PHP asked the operating system to open a connection to the host and port in your .env file โ€” and nothing answered. The connection was refused.

So this error can only mean one of two things:

  1. The database server is not running (or is not ready yet), or
  2. Laravel is looking in the wrong place โ€” wrong host, wrong port, or the right address seen from the wrong machine, which is the classic Docker trap.

It also helps to know what this error is not. If your password is wrong, you get 1045 Access denied. If the database name is wrong, you get 1049 Unknown database. If you see 2002, do not waste time re-checking credentials โ€” the server was never reached.

The 30-Second Test

Before changing anything, test the connection outside Laravel. This splits the problem in half:

# Is anything listening on the MySQL port?
nc -zv 127.0.0.1 3306

# Can the MySQL client itself connect?
mysql -h 127.0.0.1 -P 3306 -u root -p

Read the results like this:

  • nc says "Connection refused" โ†’ the server is down, crashed, or listening on a different port. Laravel is innocent. Go to Fix 1 and Fix 3.
  • nc succeeds but the mysql client fails โ†’ the server is up. Now compare what the client used (host, port) with what your .env says. Go to Fix 2 and Fix 6.
  • Both succeed, but Laravel still fails โ†’ Laravel is reading different settings than the ones you are looking at. That is almost always the config cache โ€” Fix 6.

Fix 1: The MySQL Server Is Not Running

This is the most common cause, especially after a reboot, a crashed service, or a fresh VPS setup. On Linux:

# Check the status
sudo systemctl status mysql      # Ubuntu / Debian
sudo systemctl status mariadb    # if you use MariaDB

# Start it now AND make it start on boot
sudo systemctl enable --now mysql

The --now flag is the part people miss: enable alone waits until the next reboot, start alone breaks again at the next reboot. enable --now does both.

On a local machine with XAMPP, MAMP, Laragon or a similar tool, open the tool's control panel and confirm MySQL is actually started โ€” these tools do not always restart their services after a system update or a crash. Then confirm Laravel can see the database:

php artisan migrate:status

Fix 2: localhost vs 127.0.0.1 โ€” the Socket Trap

In PHP's MySQL driver, localhost and 127.0.0.1 are not the same thing:

  • DB_HOST=localhost โ†’ PHP connects through a Unix socket file (something like /var/run/mysqld/mysqld.sock) and ignores the port.
  • DB_HOST=127.0.0.1 โ†’ PHP makes a normal TCP connection to that IP and port.

If your MySQL server created its socket somewhere PHP does not expect โ€” which happens with Docker-based tools, standalone MySQL installers, and many local dev setups โ€” localhost fails instantly even though the server is running perfectly.

The fix is to force TCP in your .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_user
DB_PASSWORD=your_password

A close relative of this error is SQLSTATE[HY000] [2002] No such file or directory. That is the same problem seen from the other side: PHP went looking for the socket file and it was not there. The fix is identical โ€” switch the host to 127.0.0.1.

Fix 3: The Port Does Not Match

MySQL normally listens on port 3306, but plenty of setups move it: a second MySQL installation, MAMP (which often uses 8889), a Docker port mapping like 3307:3306, or a server where 3306 was already taken.

Check where your server is actually listening:

sudo ss -tlnp | grep mysql
# or
mysql -u root -p -e "SHOW VARIABLES LIKE 'port';"

Then make DB_PORT in .env match that number exactly. A mismatch here produces connection refused every single time, and it is easy to miss because everything else in the file looks right.

Fix 4: Docker and Laravel Sail โ€” localhost Points at Your Own Container

Inside Docker, 127.0.0.1 means this container โ€” not your computer, and not the database container. So a Laravel container with DB_HOST=127.0.0.1 is asking itself whether it runs MySQL. It does not, so the connection is refused.

Containers on the same Compose network reach each other by service name. With Laravel Sail, the database service is called mysql:

DB_HOST=mysql
DB_PORT=3306

If your own docker-compose.yml names the service db or database, use that exact name instead. And run your Artisan commands inside the app container, where this .env view of the world is true:

./vendor/bin/sail artisan migrate
# or
docker compose exec app php artisan migrate

Running plain php artisan migrate on your host machine with a container-style .env (or the reverse) is one of the most common ways this error appears "out of nowhere".

Fix 5: It Works Sometimes โ€” the Server Is Not Ready Yet

If the error appears right after docker compose up or a server restart and then disappears on retry, your settings are fine. You are connecting during the gap between "the container/process has started" and "MySQL has finished starting and accepts connections". MySQL needs a few seconds to initialise, especially on a first boot when it is creating its data files.

For Docker, the durable fix is a healthcheck plus a condition, so the app container waits for a ready database instead of a merely started one:

services:
  app:
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 5s
      retries: 10

A plain depends_on: - mysql does not do this โ€” it only waits for the container to start, which is exactly the gap you are falling into.

Fix 6: Laravel Is Reading a Cached Config

You fixed .env, you are sure the values are right, and Laravel still connects to the old host. That happens when the configuration has been cached with php artisan config:cache โ€” from that moment on, Laravel ignores .env completely and uses the cached copy.

Clear it and try again:

php artisan config:clear
php artisan migrate:status

Rule of thumb: on your own machine, never leave a config cache in place. Save config:cache for production deployments, and rebuild it every time you deploy.

On a VPS: One Extra Check

If the app and the database live on the same server, the fixes above cover you. If Laravel must reach MySQL on a different server, one more thing can refuse the connection: by default MySQL only listens on 127.0.0.1. On the database server, check the bind-address in the MySQL config (often /etc/mysql/mysql.conf.d/mysqld.cnf), make sure the firewall allows port 3306 from your app server's IP only, and confirm the MySQL user is allowed to connect from that host. Never open 3306 to the whole internet to make this error go away โ€” that trades a small problem for a much bigger one.

Quick Checklist

When SQLSTATE[HY000] [2002] Connection refused shows up, work through this list in order:

  1. Test outside Laravel with nc -zv <host> <port> โ€” is anything listening at all?
  2. Is MySQL actually running? systemctl status mysql, and enabled on boot?
  3. Change DB_HOST=localhost to 127.0.0.1 to rule out the socket trap.
  4. Confirm DB_PORT matches the port MySQL is really listening on.
  5. In Docker, use the service name (mysql) as the host and run Artisan inside the container.
  6. If it fails only on a cold start, add a healthcheck and wait for service_healthy.
  7. Run php artisan config:clear so Laravel reads the .env you actually edited.

Conclusion

SQLSTATE[HY000] [2002] Connection refused is blunt, but it is honest: PHP could not reach a MySQL server at the address it was given. Your queries, migrations and credentials are not involved yet. Start the server, point the host and port at where it really listens, respect the Docker boundary, and clear the config cache โ€” in that order, and this error stops being a mystery and becomes a two-minute fix.

Was this helpful? 0 likes Login to like & bookmark
RH

Written by

Raja Hunain

Full Stack Developer at Raja Dev Solutions โ€” writes about real development work, the errors he faced and exactly how he fixed them, plus practical Laravel, PHP, JavaScript and MySQL tutorials.

More about the author

Comments (0)

No comments yet. Be the first to comment.

Leave a comment

Comments are moderated and appear after approval.

Keep reading

Related Errors & Articles