You run php artisan migrate, and instead of a clean table list you get a wall of red. MySQL connection errors in Laravel all look similar at first glance, but each SQLSTATE code points at a different problem — and a different fix. These are the five I see most often, what each one actually means, and the fix that works.
1. SQLSTATE[HY000] [2002] Connection refused
The most common one. PHP asked the operating system to open a connection to the host and port in your .env — and nothing answered. No SQL ran, and your username and password were never even checked.
Fix: first check whether MySQL is actually running (sudo systemctl status mysql), then check the host and port. The classic trap is DB_HOST=localhost, which makes PHP use a Unix socket instead of TCP. Switching to DB_HOST=127.0.0.1 fixes it in most local setups.
2. SQLSTATE[HY000] [1045] Access denied
This one is different: the server was reached, but it rejected your credentials. So this is the only error on this list where the username and password are actually the problem.
Fix: verify the user exists in MySQL and has rights on your database, and check for typos in DB_USERNAME and DB_PASSWORD. Also confirm the user is allowed to connect from your host — a user created for localhost cannot always connect over 127.0.0.1.
3. SQLSTATE[HY000] [1049] Unknown database
The server is up, the credentials are right, but the database name in .env does not exist on that server.
Fix: create it (CREATE DATABASE your_database;) or correct DB_DATABASE. This one appears constantly after cloning a project on a fresh machine, because the .env travels with the code but the database does not.
4. SQLSTATE[HY000] [2002] No such file or directory
Same family as error 1, seen from the other side: PHP went looking for the MySQL socket file and it was not there. Again, localhost is the trigger.
Fix: identical — switch DB_HOST to 127.0.0.1 so PHP connects over TCP instead of hunting for a socket file.
5. SQLSTATE[HY000] [2006] MySQL server has gone away
Your app connected fine, then the connection died mid-request. Long-running imports, huge queries, or a server that closed an idle connection are the usual causes.
Fix: for imports, process rows in chunks instead of loading everything at once. If it happens on idle connections, check the server's wait_timeout — and in queued jobs, reconnect before heavy work instead of assuming the connection from the start of the job is still alive.
The habit that saves the most time
When a connection error appears, do not start by editing .env at random. Test outside Laravel first — nc -zv 127.0.0.1 3306 tells you in one second whether anything is listening at all. If nothing is listening, Laravel is innocent and the server is the problem. If something is listening, compare what the MySQL client used with what your .env says. That one test splits every error on this list in half.
One more habit: after any .env change, run php artisan config:clear. A cached config makes Laravel ignore your .env completely, and you will keep debugging a problem you already fixed.
If you want the full walkthrough for the first error on this list — all six causes of Connection refused, including the Docker trap and the startup race — it is here: https://rajadevsolutions.online/errors/how-to-fix-sqlstate-hy000-2002-connection-refused-laravel
Which of these five wasted the most of your time? I am curious which one I missed.
Top comments (0)