Fixing SQLSTATE[HY000] [2002] Connection Refused in Laravel (Local, Docker & Sail)
Nothing derails a backend sprint faster than spinning up a Laravel project, running php artisan migrate , and getting hit with a wall of red terminal text: Illuminate\Database\QueryException SQLSTATE[HY000] [2002] Connection refused (Connection: mysql, SQL: select * from information_schema.tables where table_schema = app_db and table_name = migrations and table_type = 'BASE TABLE') Unlike…
When working with Laravel, encountering the error message Fixing SQLSTATE[HY000] [2002] Connection Refused can be frustrating. This error occurs at the networking layer, before MySQL even checks your username or password. There are five main root causes for this specific error:
1. 127.0.0.1 vs. localhost Socket Trap: PHP's MySQL PDO driver treats localhost and 127.0.0.1 differently. If you use localhost, PHP connects via a local Unix domain socket file. Using 127.0.0.1 forces a standard TCP/IP network connection over port 3306. To fix this, explicitly use the IPv4 loopback address (127.0.0.1) in your .env file, and clear the config cache with php artisan config:clear after changing credentials.
2. Docker & Laravel Sail Networking Mistakes: When running an app inside Docker or Laravel Sail, each container gets its own isolated network interface. If your PHP container uses DB_HOST=127.0.0.1, PHP looks for MySQL inside the PHP container itself, where MySQL doesn't exist. For commands inside the container, set DB_HOST to the container service name (mysql). For Artisan commands from the host machine, route them through the container using ./vendor/bin/sail artisan migrate.
3. MySQL Service Stopped or Crashed: The MySQL daemon might not be running due to resource constraints, such as low memory. Check if MySQL is active with sudo systemctl status mysql (Linux) or brew services list and brew services restart mysql (macOS). If the service is stopped, start it again with sudo systemctl start mysql (Linux) or brew services restart mysql (macOS). Alternatively, check for port 3306 usage with Get-NetTCPConnection (Windows) and start the MySQL engine if needed.
4. Silent Port Collisions (3306 vs 3307): Multiple MySQL instances may fight over port 3306 when using native MySQL installations and then switching to Docker or DBngin. To resolve this, verify if port 3306 is in use with sudo lsof -i :3306 (Linux/macOS) or netstat -ano | findstr :3306 (Windows). Check the database GUI client (TablePlus, DBeaver) and update the .env file accordingly (DB_HOST = 127.0.0.1, DB_PORT = 3307).
5. Custom Unix Sockets (MAMP & Shared Hosting): If using MAMP or shared hosting, custom Unix sockets can cause issues. Ensure that your .env file explicitly specifies the correct socket path and database details. Clear the config cache afterward with php artisan config:clear to ensure Laravel reads the updated .env file.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
