Laravel 6.4.1 SQLSTATE[HY000] [2002] Connection refused

Laravel 6.4.1 SQLSTATE[HY000] [2002] Connection refused

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoding Laravel's SQLSTATE[HY000] [2002] Connection refused Error

When you run php artisan migrate and immediately hit a wall with SQLSTATE[HY000] [2002] Connection refused, the error message is technically specific, but the root cause often lies in how your application perceives the database server versus how that server actually exists on your local machine. This specific error indicates that the PHP process cannot establish a TCP/IP connection to the MySQL port defined in your configuration.

In the scenario described with XAMPP 7.3.11 on macOS Mojave, the user observes that phpMyAdmin runs successfully on http://127.0.0.1:8080. This confirms two critical facts: the web server (Apache/Nginx) is running, and the database service appears to be active enough to serve HTTP requests through the PHP interface. However, Laravel's migration runner connects directly to the MySQL socket or TCP port using the credentials provided in the .env file.

The error SQLSTATE[HY000] [2002] Connection refused typically points to one of two underlying issues: the MySQL service is not actually listening on the expected network interface, or the host/port configuration in the .env file does not match the actual connection parameters of the running XAMPP instance.

The Hostname Trap: 127.0.0.1 vs localhost

A common misconception in local development environments involves the distinction between 127.0.0.1 and localhost. While they often resolve to the same IP address, MySQL server configurations can differ in how they bind to these names.

In many XAMPP distributions, particularly on macOS, the default configuration might bind the MySQL server specifically to the Unix socket file rather than listening on a TCP/IP port for local connections, or it may listen only on localhost but not respond when queried via the explicit IP string 127.0.0.1 depending on the bind-address setting in my.ini.

If your .env file specifies:

DB_HOST=127.0.0.1
DB_PORT=3306

You are explicitly requesting a TCP connection to port 3306. If the XAMPP MySQL service is configured to listen on the Unix socket (which is the default behavior for many installations) or if the bind-address in my.ini is set strictly to 127.0.0.1 but the service isn't actually accepting TCP connections, the connection will be refused.

To troubleshoot this, verify how your specific XAMPP instance is configured. Check the my.ini file located within your XAMPP installation directory. Look for the [mysqld] section and examine the bind-address directive.

  • If it says 127.0.0.1, TCP connections are intended but must be allowed by firewall or security settings.
  • If it is commented out, MySQL usually binds to all available interfaces (0.0.0.0).

If you are unsure, changing the .env configuration to use localhost instead of 127.0.0.1 is a robust first step. On many Linux and macOS systems, localhost resolves via /etc/hosts to a Unix socket connection rather than forcing a TCP handshake, which aligns better with default XAMPP configurations.

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

Verifying the Service State

The error message "Connection refused" is distinct from "Connection timed out." A timeout implies the host exists but didn't reply; "refused" means a device actively rejected the packet. In the context of XAMPP, this often happens when the MySQL service appears to be running (because you can see it in the control panel) but isn't actually accepting new connections on the specified port.

You can verify if the port is open using system utilities like lsof or netstat. On macOS, run:

lsof -i :3306

If this command returns no output, MySQL is not listening on port 3306 at all. This might happen if the service crashed silently or if it was configured to use a different port (e.g., if XAMPP was installed in a custom directory and the port number changed).

Additionally, ensure that the mysql service within the XAMPP control panel is actually started. Sometimes the dashboard shows services as active, but the specific MySQL daemon process has detached or failed to bind properly. Restarting the MySQL module from the XAMPP Control Panel is often the most effective reset for these local environment issues.

Security and Firewall Considerations

While less likely on a development machine, macOS firewall settings can sometimes interfere with incoming connections if you are trying to connect from a different network interface (e.g., connecting via SSH). However, since this error occurs during php artisan migrate, which runs locally, the issue is almost certainly a configuration mismatch between what Laravel expects and what XAMPP provides.

If you have modified the my.ini file to change the port, remember that you must update both the .env file and the actual running service. Changing the port in XAMPP requires stopping the MySQL service, editing the config, restarting the service, and then updating the database configuration in your Laravel project.

For more advanced setups involving Docker or custom XAMPP configurations, ensure that the socket path is correctly handled if you are not using TCP/IP. Laravel supports connecting via sockets by setting DB_HOST to an empty string or a specific socket path, though this is less common in standard XAMPP workflows.

By aligning the host configuration (localhost vs 127.0.0.1) and ensuring the MySQL service is actively listening on port 3306, you can resolve the connection refused error and proceed with migrations successfully. If issues persist after these checks, reviewing the XAMPP error logs (usually found in xampp/mysql/data/error.log) will provide deeper insights into why the server is refusing connections.

Our network