PHP Laravel: No connection could be made because the target machine actively refused it

PHP Laravel: No connection could be made because the target machine actively refused it

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

Stefan Bogdanescu

Founder & Senior Architect

PHP Laravel: No connection could be made because the target machine actively refused it

When you encounter the SQLSTATE[HY000] [2002] error in a Laravel application, specifically the message "No connection could be made because the target machine actively refused it," it is immediately clear that the issue lies at the network or socket level, not within your application logic. Unlike an authentication failure or a missing table, this error indicates that the PHP process attempting to connect to the database server cannot even establish a TCP handshake with the MySQL server.

The scenario where you can successfully run mysql -u homestead -psecret homestead via SSH but fail when running php artisan serve highlights a specific architectural mismatch common in virtualized environments like Homestead or Vagrant. The ability to connect from the command line suggests that your credentials are correct and the MySQL service is running on the host machine. However, the refusal of the connection implies a firewall rule, a socket path mismatch, or a binding address restriction that prevents the PHP process from reaching the database listener.

In many virtualized setups, the operating system running Laravel might be different from the one running the MySQL server, or they might be on completely separate networks despite appearing to be part of the same project. If you are connecting locally on a single machine, the most common culprit is that the MySQL server is not listening on the default TCP port (3306) for external connections, but rather only bound to the local Unix socket file (usually at /var/run/mysqld/mysqld.sock or similar).

When you execute the mysql command from a terminal inside the same virtual machine, the client library automatically detects the Unix socket and connects via that file path. However, Laravel's default configuration in config/database.php attempts to connect over TCP/IP using DB_HOST=localhost. If the MySQL server is not explicitly configured to listen on all network interfaces (0.0.0.0) or if a firewall (such as ufw, iptables, or Windows Firewall) blocks port 3306, the connection attempt will be refused by the OS kernel before it reaches the database service.

To resolve this without compromising security, you should verify how your MySQL server is bound. Check the configuration file, typically located at /etc/mysql/mysql.conf.d/mysqld.cnf or within the main my.cnf file, for the bind-address directive.

  • If it is set to 127.0.0.1, the server only accepts connections from the local loopback interface. While this often works for local socket connections, it can sometimes fail depending on how the client resolves localhost.
  • Changing this to 0.0.0.0 allows the server to listen on all available network interfaces, which is necessary if the application and database are running in different containers or VMs.

Additionally, ensure that the firewall rules permit traffic on port 3306. If you are using UFW (common in Ubuntu-based Homestead boxes), you would need to run sudo ufw allow 3306/tcp. Remember that allowing this port exposes your database to the network; if this is a development environment accessible only via SSH, ensure your SSH access is secured first.

Another frequent pitfall involves the distinction between localhost and 127.0.0.1. In some environments, localhost resolves to the Unix socket rather than an IP address. If your MySQL server is configured strictly for TCP/IP connections but you use localhost, the PHP PDO driver might try to find a socket that doesn't exist or fail to resolve the hostname correctly within the Laravel context. Switching the DB_HOST in your .env file from localhost to 127.0.0.1 can often bypass hostname resolution issues and force a direct TCP connection attempt.

If you are working with Dockerized environments, the issue might be that the container cannot reach the host's database service because of missing port mappings or network bridge configurations. In such cases, ensuring that the docker-compose.yml file correctly maps the database port (e.g., - 3306:3306) is critical.

Finally, always verify that the .env file is being read correctly. Laravel uses the env() helper in config/database.php to pull values from the environment file, falling back to defaults if they are missing. Ensure that your .env file contains valid credentials and that the database name matches exactly what exists on the server. A mismatch here will usually result in an "Unknown database" error rather than a connection refusal, but confirming the exact host resolution is the first step in debugging HY000 errors.

For developers looking to streamline their local development environment management, especially when dealing with complex networking issues between Laravel and MySQL, consulting resources like LaravelCompany can provide insights into best practices for configuring virtual machines and container orchestration.

Our network